@liftitinc/geocoding 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,204 @@
+import { GeocodeRequest, GeocodeResponse, ReverseGeocodeRequest, ReverseGeocodeResponse } from '@geocoding/shared';
+export { ApiResponse, GeocodeRequest, GeocodeRequestWire, GeocodeResponse, GeocodeResponseWire, ReverseGeocodeRequest, ReverseGeocodeRequestWire, ReverseGeocodeResponse, ReverseGeocodeResponseWire, addressComponentsWireSchema, geocodeRequestWireSchema, geocodeResponseWireSchema, locationWireSchema, reverseGeocodeRequestWireSchema, reverseGeocodeResponseWireSchema, zoneWireSchema } from '@geocoding/shared';
+
+/**
+ * Configuration for retry behavior
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts (default: 3)
+     */
+    maxRetries: number;
+    /**
+     * Initial delay in milliseconds (default: 1000)
+     */
+    baseDelay: number;
+    /**
+     * Maximum delay cap in milliseconds (default: 30000)
+     */
+    maxDelay: number;
+    /**
+     * Multiplier for exponential growth (default: 2)
+     */
+    timeMultiple: number;
+}
+interface GeocodingClientConfig {
+    /**
+     * API key for authentication (required)
+     */
+    apiKey: string;
+    /**
+     * Base URL for the API (optional, defaults to production)
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds (optional, defaults to 10000)
+     */
+    timeout?: number;
+    /**
+     * Maximum number of retry attempts (optional, defaults to 3)
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay for retries in milliseconds (optional, defaults to 1000)
+     */
+    baseDelay?: number;
+    /**
+     * Maximum delay cap for retries in milliseconds (optional, defaults to 30000)
+     */
+    maxDelay?: number;
+}
+interface RequestOptions {
+    /**
+     * AbortSignal for request cancellation
+     */
+    signal?: AbortSignal;
+}
+
+/**
+ * Client for the Liftit Geocoding API
+ *
+ * @example
+ * ```typescript
+ * const client = new GeocodingClient({ apiKey: 'your-api-key' });
+ *
+ * // Forward geocoding
+ * const result = await client.geocode({
+ *   country: 'co',
+ *   city: 'Bogota',
+ *   address: 'Calle 100 # 19-61'
+ * });
+ *
+ * // Reverse geocoding
+ * const address = await client.reverseGeocode({
+ *   lat: 4.6097,
+ *   lng: -74.0817
+ * });
+ * ```
+ */
+declare class GeocodingClient {
+    private readonly config;
+    private readonly httpClient;
+    constructor(config: GeocodingClientConfig);
+    /**
+     * Convert an address to geographic coordinates
+     *
+     * @param request - Geocode request parameters
+     * @param options - Optional request options
+     * @returns Geocode response with coordinates
+     * @throws {ValidationError} If request parameters are invalid
+     * @throws {AuthenticationError} If API key is invalid
+     * @throws {RateLimitError} If rate limit is exceeded
+     * @throws {UpstreamError} If upstream API returns an error
+     */
+    geocode(request: GeocodeRequest, options?: RequestOptions): Promise<GeocodeResponse>;
+    /**
+     * Convert geographic coordinates to an address
+     *
+     * @param request - Reverse geocode request parameters
+     * @param options - Optional request options
+     * @returns Reverse geocode response with address
+     * @throws {ValidationError} If request parameters are invalid
+     * @throws {AuthenticationError} If API key is invalid
+     * @throws {RateLimitError} If rate limit is exceeded
+     * @throws {UpstreamError} If upstream API returns an error
+     */
+    reverseGeocode(request: ReverseGeocodeRequest, options?: RequestOptions): Promise<ReverseGeocodeResponse>;
+}
+
+/**
+ * Base error class for all SDK errors
+ */
+declare class GeocodeError extends Error {
+    readonly code: string;
+    readonly requestId?: string;
+    constructor(message: string, code: string, requestId?: string);
+}
+/**
+ * Thrown when request validation fails
+ */
+declare class ValidationError extends GeocodeError {
+    constructor(message: string, requestId?: string);
+}
+/**
+ * Thrown when API key is invalid or missing
+ */
+declare class AuthenticationError extends GeocodeError {
+    constructor(message: string, requestId?: string);
+}
+/**
+ * Thrown when rate limit is exceeded
+ */
+declare class RateLimitError extends GeocodeError {
+    readonly retryAfter?: number;
+    readonly limit?: number;
+    readonly remaining?: number;
+    constructor(message: string, requestId?: string, retryAfter?: number, limit?: number, remaining?: number);
+    /**
+     * Calculate optimal retry delay respecting rate limit reset time.
+     * Returns milliseconds to wait before retrying.
+     * Adds small jitter (0-1000ms) to prevent thundering herd.
+     *
+     * @returns Milliseconds to wait before retrying
+     */
+    getRetryDelay(): number;
+}
+/**
+ * Thrown when upstream Liftit API returns an error
+ */
+declare class UpstreamError extends GeocodeError {
+    readonly statusCode?: number;
+    constructor(message: string, requestId?: string, statusCode?: number);
+}
+
+/**
+ * Default retry configuration values
+ */
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Calculate delay for retry attempt using exponential backoff with full jitter.
+ *
+ * Formula: Math.floor(Math.random() * Math.min(baseDelay * timeMultiple^attempt, maxDelay))
+ *
+ * Full jitter (random between 0 and calculated cap) prevents thundering herd
+ * when multiple clients retry simultaneously.
+ *
+ * @param attempt - Zero-based retry attempt number (0 for first retry)
+ * @param config - Retry configuration
+ * @returns Delay in milliseconds (integer)
+ */
+declare function calculateDelay(attempt: number, config: RetryConfig): number;
+/**
+ * Determine if an error is retryable (transient failure that might succeed on retry).
+ *
+ * Retryable errors:
+ * - RateLimitError (429) - rate limit will reset
+ * - UpstreamError (502, 504) - upstream service issues are transient
+ * - TIMEOUT_ERROR - network delays may resolve
+ * - NETWORK_ERROR - connectivity issues may resolve
+ *
+ * Non-retryable errors:
+ * - ValidationError (400) - bad request won't fix itself
+ * - AuthenticationError (401) - invalid API key won't become valid
+ * - ABORT_ERROR - user explicitly cancelled
+ * - Other errors - unknown, don't retry
+ *
+ * @param error - The error to check
+ * @returns true if the error is retryable
+ */
+declare function isRetryableError(error: GeocodeError): boolean;
+/**
+ * Sleep for a specified duration, with support for abort signal.
+ *
+ * If the abort signal is already aborted, rejects immediately.
+ * If the signal is aborted during the sleep, clears the timeout and rejects.
+ *
+ * Uses { once: true } on addEventListener to prevent memory leaks in long-running processes.
+ *
+ * @param ms - Duration to sleep in milliseconds
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns Promise that resolves after the delay or rejects on abort
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+
+export { AuthenticationError, DEFAULT_RETRY_CONFIG, GeocodeError, GeocodingClient, type GeocodingClientConfig, RateLimitError, type RequestOptions, type RetryConfig, UpstreamError, ValidationError, calculateDelay, isRetryableError, sleep };

package/dist/index.d.ts

@@ -0,0 +1,204 @@
+import { GeocodeRequest, GeocodeResponse, ReverseGeocodeRequest, ReverseGeocodeResponse } from '@geocoding/shared';
+export { ApiResponse, GeocodeRequest, GeocodeRequestWire, GeocodeResponse, GeocodeResponseWire, ReverseGeocodeRequest, ReverseGeocodeRequestWire, ReverseGeocodeResponse, ReverseGeocodeResponseWire, addressComponentsWireSchema, geocodeRequestWireSchema, geocodeResponseWireSchema, locationWireSchema, reverseGeocodeRequestWireSchema, reverseGeocodeResponseWireSchema, zoneWireSchema } from '@geocoding/shared';
+
+/**
+ * Configuration for retry behavior
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts (default: 3)
+     */
+    maxRetries: number;
+    /**
+     * Initial delay in milliseconds (default: 1000)
+     */
+    baseDelay: number;
+    /**
+     * Maximum delay cap in milliseconds (default: 30000)
+     */
+    maxDelay: number;
+    /**
+     * Multiplier for exponential growth (default: 2)
+     */
+    timeMultiple: number;
+}
+interface GeocodingClientConfig {
+    /**
+     * API key for authentication (required)
+     */
+    apiKey: string;
+    /**
+     * Base URL for the API (optional, defaults to production)
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds (optional, defaults to 10000)
+     */
+    timeout?: number;
+    /**
+     * Maximum number of retry attempts (optional, defaults to 3)
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay for retries in milliseconds (optional, defaults to 1000)
+     */
+    baseDelay?: number;
+    /**
+     * Maximum delay cap for retries in milliseconds (optional, defaults to 30000)
+     */
+    maxDelay?: number;
+}
+interface RequestOptions {
+    /**
+     * AbortSignal for request cancellation
+     */
+    signal?: AbortSignal;
+}
+
+/**
+ * Client for the Liftit Geocoding API
+ *
+ * @example
+ * ```typescript
+ * const client = new GeocodingClient({ apiKey: 'your-api-key' });
+ *
+ * // Forward geocoding
+ * const result = await client.geocode({
+ *   country: 'co',
+ *   city: 'Bogota',
+ *   address: 'Calle 100 # 19-61'
+ * });
+ *
+ * // Reverse geocoding
+ * const address = await client.reverseGeocode({
+ *   lat: 4.6097,
+ *   lng: -74.0817
+ * });
+ * ```
+ */
+declare class GeocodingClient {
+    private readonly config;
+    private readonly httpClient;
+    constructor(config: GeocodingClientConfig);
+    /**
+     * Convert an address to geographic coordinates
+     *
+     * @param request - Geocode request parameters
+     * @param options - Optional request options
+     * @returns Geocode response with coordinates
+     * @throws {ValidationError} If request parameters are invalid
+     * @throws {AuthenticationError} If API key is invalid
+     * @throws {RateLimitError} If rate limit is exceeded
+     * @throws {UpstreamError} If upstream API returns an error
+     */
+    geocode(request: GeocodeRequest, options?: RequestOptions): Promise<GeocodeResponse>;
+    /**
+     * Convert geographic coordinates to an address
+     *
+     * @param request - Reverse geocode request parameters
+     * @param options - Optional request options
+     * @returns Reverse geocode response with address
+     * @throws {ValidationError} If request parameters are invalid
+     * @throws {AuthenticationError} If API key is invalid
+     * @throws {RateLimitError} If rate limit is exceeded
+     * @throws {UpstreamError} If upstream API returns an error
+     */
+    reverseGeocode(request: ReverseGeocodeRequest, options?: RequestOptions): Promise<ReverseGeocodeResponse>;
+}
+
+/**
+ * Base error class for all SDK errors
+ */
+declare class GeocodeError extends Error {
+    readonly code: string;
+    readonly requestId?: string;
+    constructor(message: string, code: string, requestId?: string);
+}
+/**
+ * Thrown when request validation fails
+ */
+declare class ValidationError extends GeocodeError {
+    constructor(message: string, requestId?: string);
+}
+/**
+ * Thrown when API key is invalid or missing
+ */
+declare class AuthenticationError extends GeocodeError {
+    constructor(message: string, requestId?: string);
+}
+/**
+ * Thrown when rate limit is exceeded
+ */
+declare class RateLimitError extends GeocodeError {
+    readonly retryAfter?: number;
+    readonly limit?: number;
+    readonly remaining?: number;
+    constructor(message: string, requestId?: string, retryAfter?: number, limit?: number, remaining?: number);
+    /**
+     * Calculate optimal retry delay respecting rate limit reset time.
+     * Returns milliseconds to wait before retrying.
+     * Adds small jitter (0-1000ms) to prevent thundering herd.
+     *
+     * @returns Milliseconds to wait before retrying
+     */
+    getRetryDelay(): number;
+}
+/**
+ * Thrown when upstream Liftit API returns an error
+ */
+declare class UpstreamError extends GeocodeError {
+    readonly statusCode?: number;
+    constructor(message: string, requestId?: string, statusCode?: number);
+}
+
+/**
+ * Default retry configuration values
+ */
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Calculate delay for retry attempt using exponential backoff with full jitter.
+ *
+ * Formula: Math.floor(Math.random() * Math.min(baseDelay * timeMultiple^attempt, maxDelay))
+ *
+ * Full jitter (random between 0 and calculated cap) prevents thundering herd
+ * when multiple clients retry simultaneously.
+ *
+ * @param attempt - Zero-based retry attempt number (0 for first retry)
+ * @param config - Retry configuration
+ * @returns Delay in milliseconds (integer)
+ */
+declare function calculateDelay(attempt: number, config: RetryConfig): number;
+/**
+ * Determine if an error is retryable (transient failure that might succeed on retry).
+ *
+ * Retryable errors:
+ * - RateLimitError (429) - rate limit will reset
+ * - UpstreamError (502, 504) - upstream service issues are transient
+ * - TIMEOUT_ERROR - network delays may resolve
+ * - NETWORK_ERROR - connectivity issues may resolve
+ *
+ * Non-retryable errors:
+ * - ValidationError (400) - bad request won't fix itself
+ * - AuthenticationError (401) - invalid API key won't become valid
+ * - ABORT_ERROR - user explicitly cancelled
+ * - Other errors - unknown, don't retry
+ *
+ * @param error - The error to check
+ * @returns true if the error is retryable
+ */
+declare function isRetryableError(error: GeocodeError): boolean;
+/**
+ * Sleep for a specified duration, with support for abort signal.
+ *
+ * If the abort signal is already aborted, rejects immediately.
+ * If the signal is aborted during the sleep, clears the timeout and rejects.
+ *
+ * Uses { once: true } on addEventListener to prevent memory leaks in long-running processes.
+ *
+ * @param ms - Duration to sleep in milliseconds
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns Promise that resolves after the delay or rejects on abort
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+
+export { AuthenticationError, DEFAULT_RETRY_CONFIG, GeocodeError, GeocodingClient, type GeocodingClientConfig, RateLimitError, type RequestOptions, type RetryConfig, UpstreamError, ValidationError, calculateDelay, isRetryableError, sleep };