@autolink/sdk 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,304 @@
+interface RetryConfig {
+    attempts: number;
+    backoff: "exponential" | "linear";
+}
+
+interface FetcherConfig {
+    apiKey: string;
+    timeout: number;
+    retry: RetryConfig;
+    debug: boolean;
+}
+
+interface GatewayPagination {
+    total: number;
+    page: number;
+    page_size: number;
+    pages: number;
+}
+interface GatewayMeta {
+    request_id: string;
+    pagination?: GatewayPagination;
+}
+interface GatewayEnvelope<T> {
+    data: T;
+    meta: GatewayMeta;
+}
+type StockStatus = "available" | "reserved" | "sold" | "in_transit";
+type VehicleCondition = "new" | "locally_used" | "foreign_used";
+/** @deprecated Use cover_image / cover_image_variants instead */
+interface VehiclePhoto {
+    url: string;
+    is_primary: boolean;
+    caption?: string;
+}
+interface CoverImageVariants {
+    thumb: string;
+    medium: string;
+    large: string;
+    master: string;
+}
+interface VehicleDealer {
+    name: string;
+    slug: string;
+    logo?: string;
+    city?: string;
+    whatsapp_number?: string;
+    public_url?: string;
+}
+interface AutolinkVehicle {
+    /** UUID — internal identifier */
+    id: string;
+    /** URL-safe slug — use this for routes and API calls */
+    slug: string;
+    title: string;
+    make: string;
+    make_id?: string;
+    model: string;
+    model_id?: string;
+    year: number;
+    body_type: string;
+    body_type_display?: string;
+    colour?: string;
+    condition: VehicleCondition;
+    mileage_km?: number;
+    engine_size?: number;
+    fuel_type?: string;
+    fuel_type_display?: string;
+    transmission?: string;
+    transmission_display?: string;
+    drive_type?: string;
+    price_kes: number;
+    is_negotiable?: boolean;
+    has_discount?: boolean;
+    active_discount_price_kes?: number | null;
+    location?: string;
+    stock_status: StockStatus;
+    stock_status_display?: string;
+    is_featured?: boolean;
+    description?: string;
+    features?: string[];
+    /** Primary image URL */
+    cover_image?: string;
+    cover_image_variants?: CoverImageVariants;
+    /** @deprecated Use cover_image instead */
+    photos?: VehiclePhoto[];
+    listing_status?: "published";
+    published_at: string;
+    dealer?: VehicleDealer;
+    salesperson?: unknown;
+}
+interface InventoryListFilters {
+    make?: string;
+    model?: string;
+    year?: number;
+    min_year?: number;
+    max_year?: number;
+    condition?: VehicleCondition;
+    stock_status?: StockStatus;
+    min_price?: number;
+    max_price?: number;
+    min_mileage?: number;
+    max_mileage?: number;
+    transmission?: string;
+    fuel_type?: string;
+    body_type?: string;
+    search?: string;
+    ordering?: string;
+    page?: number;
+    page_size?: number;
+    feature_ids?: string;
+}
+interface FilterOptions {
+    makes: string[];
+    models: string[];
+    years: number[];
+    conditions: string[];
+    transmissions: string[];
+    fuel_types: string[];
+    body_types: string[];
+    stock_statuses?: string[];
+    colours?: string[];
+    price_range: {
+        min: number;
+        max: number;
+    };
+}
+interface AutolinkInquiryPayload {
+    type: "vehicle" | "general";
+    customer_name: string;
+    customer_email: string;
+    customer_phone?: string;
+    subject?: string;
+    message: string;
+    vehicle_slug?: string;
+}
+interface AutolinkInquiry {
+    id: string;
+    type: string;
+    customer_name: string;
+    customer_email: string;
+    message: string;
+    vehicle_slug?: string;
+    lead_id?: string;
+    test_mode: boolean;
+    created_at: string;
+}
+interface AutolinkProfile {
+    name: string;
+    slug: string;
+    tagline?: string;
+    description?: string;
+    phone?: string;
+    email?: string;
+    address?: string;
+    city?: string;
+    country?: string;
+    logo_url?: string;
+    cover_url?: string;
+    is_publicly_visible: boolean;
+}
+interface ArticleListFilters {
+    page?: number;
+    page_size?: number;
+    search?: string;
+    ordering?: string;
+}
+interface AutolinkArticle {
+    slug: string;
+    title: string;
+    excerpt?: string;
+    /** Raw HTML from the CMS — sanitize before rendering */
+    body: string;
+    cover_image_url?: string;
+    status: "published";
+    published_at: string;
+    author?: string;
+}
+interface IntegrationStatus {
+    ok: boolean;
+    environment: "test" | "live";
+    tenant: {
+        slug: string;
+        name: string;
+    };
+    scopes: string[];
+    api_version: string;
+}
+
+interface AutolinkCache {
+    get(key: string): Promise<unknown> | unknown;
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+}
+declare class MemoryCache implements AutolinkCache {
+    private store;
+    get(key: string): unknown;
+    set(key: string, value: unknown, ttlSeconds?: number): void;
+    delete(key: string): void;
+    /** Remove all expired entries. Optional maintenance call. */
+    purgeExpired(): void;
+}
+
+declare class InventoryResource {
+    private config;
+    private cache?;
+    constructor(config: FetcherConfig, cache?: AutolinkCache | undefined);
+    list(filters?: InventoryListFilters, options?: {
+        ttl?: number;
+    }): Promise<GatewayEnvelope<AutolinkVehicle[]>>;
+    get(slug: string, options?: {
+        ttl?: number;
+    }): Promise<GatewayEnvelope<AutolinkVehicle>>;
+    filterOptions(options?: {
+        ttl?: number;
+    }): Promise<GatewayEnvelope<FilterOptions>>;
+    pages(filters?: Omit<InventoryListFilters, "page">): AsyncGenerator<GatewayEnvelope<AutolinkVehicle[]>>;
+}
+
+interface InquiryCreateOptions {
+    idempotencyKey?: string;
+}
+declare class InquiriesResource {
+    private config;
+    constructor(config: FetcherConfig);
+    create(payload: AutolinkInquiryPayload, options?: InquiryCreateOptions): Promise<GatewayEnvelope<AutolinkInquiry>>;
+}
+
+declare class ProfileResource {
+    private config;
+    constructor(config: FetcherConfig);
+    get(): Promise<GatewayEnvelope<AutolinkProfile>>;
+}
+
+declare class ArticlesResource {
+    private config;
+    private cache?;
+    constructor(config: FetcherConfig, cache?: AutolinkCache | undefined);
+    list(filters?: ArticleListFilters, options?: {
+        ttl?: number;
+    }): Promise<GatewayEnvelope<AutolinkArticle[]>>;
+    get(slug: string, options?: {
+        ttl?: number;
+    }): Promise<GatewayEnvelope<AutolinkArticle>>;
+}
+
+declare class IntegrationResource {
+    private config;
+    constructor(config: FetcherConfig);
+    check(): Promise<GatewayEnvelope<IntegrationStatus>>;
+}
+
+interface AutolinkClientConfig {
+    apiKey: string;
+    timeout?: number;
+    retry?: Partial<RetryConfig>;
+    debug?: boolean;
+    cache?: AutolinkCache;
+}
+declare class AutolinkClient {
+    readonly inventory: InventoryResource;
+    readonly inquiries: InquiriesResource;
+    readonly profile: ProfileResource;
+    readonly articles: ArticlesResource;
+    readonly integration: IntegrationResource;
+    constructor(config: AutolinkClientConfig);
+}
+
+declare class AutolinkError extends Error {
+    readonly requestId: string;
+    readonly code: string;
+    constructor(message: string, code: string, requestId: string);
+}
+declare class AutolinkAuthError extends AutolinkError {
+    constructor(message: string, requestId: string);
+}
+declare class AutolinkForbiddenError extends AutolinkError {
+    constructor(message: string, requestId: string);
+}
+declare class AutolinkNotFoundError extends AutolinkError {
+    constructor(message: string, requestId: string);
+}
+declare class AutolinkValidationError extends AutolinkError {
+    readonly fields: Record<string, string[]>;
+    constructor(message: string, requestId: string, fields?: Record<string, string[]>);
+}
+declare class AutolinkRateLimitError extends AutolinkError {
+    readonly retryAfter: number;
+    constructor(message: string, requestId: string, retryAfter: number);
+}
+declare class AutolinkNetworkError extends AutolinkError {
+    readonly cause: Error;
+    constructor(message: string, cause: Error);
+}
+
+declare const GATEWAY_BASE_URL = "https://gateway.autolink.ke";
+declare const GATEWAY_URL = "https://gateway.autolink.ke/sdk/v1";
+declare const SDK_VERSION = "0.1.0";
+
+/** Unwraps a GatewayEnvelope and returns the data directly */
+declare function unwrap<T>(envelope: GatewayEnvelope<T>): T;
+/** Returns field-level validation errors for a given field name */
+declare function getFieldErrors(error: AutolinkValidationError, field: string): string[];
+
+export { type ArticleListFilters, type AutolinkArticle, AutolinkAuthError, type AutolinkCache, AutolinkClient, type AutolinkClientConfig, AutolinkError, AutolinkForbiddenError, type AutolinkInquiry, type AutolinkInquiryPayload, AutolinkNetworkError, AutolinkNotFoundError, type AutolinkProfile, AutolinkRateLimitError, AutolinkValidationError, type AutolinkVehicle, type CoverImageVariants, type FilterOptions, GATEWAY_BASE_URL, GATEWAY_URL, type GatewayEnvelope, type GatewayMeta, type GatewayPagination, type IntegrationStatus, type InventoryListFilters, MemoryCache, SDK_VERSION, type StockStatus, type VehicleCondition, type VehicleDealer, type VehiclePhoto, getFieldErrors, unwrap };

package/dist/index.d.ts

@@ -0,0 +1,304 @@
+interface RetryConfig {
+    attempts: number;
+    backoff: "exponential" | "linear";
+}
+
+interface FetcherConfig {
+    apiKey: string;
+    timeout: number;
+    retry: RetryConfig;
+    debug: boolean;
+}
+
+interface GatewayPagination {
+    total: number;
+    page: number;
+    page_size: number;
+    pages: number;
+}
+interface GatewayMeta {
+    request_id: string;
+    pagination?: GatewayPagination;
+}
+interface GatewayEnvelope<T> {
+    data: T;
+    meta: GatewayMeta;
+}
+type StockStatus = "available" | "reserved" | "sold" | "in_transit";
+type VehicleCondition = "new" | "locally_used" | "foreign_used";
+/** @deprecated Use cover_image / cover_image_variants instead */
+interface VehiclePhoto {
+    url: string;
+    is_primary: boolean;
+    caption?: string;
+}
+interface CoverImageVariants {
+    thumb: string;
+    medium: string;
+    large: string;
+    master: string;
+}
+interface VehicleDealer {
+    name: string;
+    slug: string;
+    logo?: string;
+    city?: string;
+    whatsapp_number?: string;
+    public_url?: string;
+}
+interface AutolinkVehicle {
+    /** UUID — internal identifier */
+    id: string;
+    /** URL-safe slug — use this for routes and API calls */
+    slug: string;
+    title: string;
+    make: string;
+    make_id?: string;
+    model: string;
+    model_id?: string;
+    year: number;
+    body_type: string;
+    body_type_display?: string;
+    colour?: string;
+    condition: VehicleCondition;
+    mileage_km?: number;
+    engine_size?: number;
+    fuel_type?: string;
+    fuel_type_display?: string;
+    transmission?: string;
+    transmission_display?: string;
+    drive_type?: string;
+    price_kes: number;
+    is_negotiable?: boolean;
+    has_discount?: boolean;
+    active_discount_price_kes?: number | null;
+    location?: string;
+    stock_status: StockStatus;
+    stock_status_display?: string;
+    is_featured?: boolean;
+    description?: string;
+    features?: string[];
+    /** Primary image URL */
+    cover_image?: string;
+    cover_image_variants?: CoverImageVariants;
+    /** @deprecated Use cover_image instead */
+    photos?: VehiclePhoto[];
+    listing_status?: "published";
+    published_at: string;
+    dealer?: VehicleDealer;
+    salesperson?: unknown;
+}
+interface InventoryListFilters {
+    make?: string;
+    model?: string;
+    year?: number;
+    min_year?: number;
+    max_year?: number;
+    condition?: VehicleCondition;
+    stock_status?: StockStatus;
+    min_price?: number;
+    max_price?: number;
+    min_mileage?: number;
+    max_mileage?: number;
+    transmission?: string;
+    fuel_type?: string;
+    body_type?: string;
+    search?: string;
+    ordering?: string;
+    page?: number;
+    page_size?: number;
+    feature_ids?: string;
+}
+interface FilterOptions {
+    makes: string[];
+    models: string[];
+    years: number[];
+    conditions: string[];
+    transmissions: string[];
+    fuel_types: string[];
+    body_types: string[];
+    stock_statuses?: string[];
+    colours?: string[];
+    price_range: {
+        min: number;
+        max: number;
+    };
+}
+interface AutolinkInquiryPayload {
+    type: "vehicle" | "general";
+    customer_name: string;
+    customer_email: string;
+    customer_phone?: string;
+    subject?: string;
+    message: string;
+    vehicle_slug?: string;
+}
+interface AutolinkInquiry {
+    id: string;
+    type: string;
+    customer_name: string;
+    customer_email: string;
+    message: string;
+    vehicle_slug?: string;
+    lead_id?: string;
+    test_mode: boolean;
+    created_at: string;
+}
+interface AutolinkProfile {
+    name: string;
+    slug: string;
+    tagline?: string;
+    description?: string;
+    phone?: string;
+    email?: string;
+    address?: string;
+    city?: string;
+    country?: string;
+    logo_url?: string;
+    cover_url?: string;
+    is_publicly_visible: boolean;
+}
+interface ArticleListFilters {
+    page?: number;
+    page_size?: number;
+    search?: string;
+    ordering?: string;
+}
+interface AutolinkArticle {
+    slug: string;
+    title: string;
+    excerpt?: string;
+    /** Raw HTML from the CMS — sanitize before rendering */
+    body: string;
+    cover_image_url?: string;
+    status: "published";
+    published_at: string;
+    author?: string;
+}
+interface IntegrationStatus {
+    ok: boolean;
+    environment: "test" | "live";
+    tenant: {
+        slug: string;
+        name: string;
+    };
+    scopes: string[];
+    api_version: string;
+}
+
+interface AutolinkCache {
+    get(key: string): Promise<unknown> | unknown;
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+}
+declare class MemoryCache implements AutolinkCache {
+    private store;
+    get(key: string): unknown;
+    set(key: string, value: unknown, ttlSeconds?: number): void;
+    delete(key: string): void;
+    /** Remove all expired entries. Optional maintenance call. */
+    purgeExpired(): void;
+}
+
+declare class InventoryResource {
+    private config;
+    private cache?;
+    constructor(config: FetcherConfig, cache?: AutolinkCache | undefined);
+    list(filters?: InventoryListFilters, options?: {
+        ttl?: number;
+    }): Promise<GatewayEnvelope<AutolinkVehicle[]>>;
+    get(slug: string, options?: {
+        ttl?: number;
+    }): Promise<GatewayEnvelope<AutolinkVehicle>>;
+    filterOptions(options?: {
+        ttl?: number;
+    }): Promise<GatewayEnvelope<FilterOptions>>;
+    pages(filters?: Omit<InventoryListFilters, "page">): AsyncGenerator<GatewayEnvelope<AutolinkVehicle[]>>;
+}
+
+interface InquiryCreateOptions {
+    idempotencyKey?: string;
+}
+declare class InquiriesResource {
+    private config;
+    constructor(config: FetcherConfig);
+    create(payload: AutolinkInquiryPayload, options?: InquiryCreateOptions): Promise<GatewayEnvelope<AutolinkInquiry>>;
+}
+
+declare class ProfileResource {
+    private config;
+    constructor(config: FetcherConfig);
+    get(): Promise<GatewayEnvelope<AutolinkProfile>>;
+}
+
+declare class ArticlesResource {
+    private config;
+    private cache?;
+    constructor(config: FetcherConfig, cache?: AutolinkCache | undefined);
+    list(filters?: ArticleListFilters, options?: {
+        ttl?: number;
+    }): Promise<GatewayEnvelope<AutolinkArticle[]>>;
+    get(slug: string, options?: {
+        ttl?: number;
+    }): Promise<GatewayEnvelope<AutolinkArticle>>;
+}
+
+declare class IntegrationResource {
+    private config;
+    constructor(config: FetcherConfig);
+    check(): Promise<GatewayEnvelope<IntegrationStatus>>;
+}
+
+interface AutolinkClientConfig {
+    apiKey: string;
+    timeout?: number;
+    retry?: Partial<RetryConfig>;
+    debug?: boolean;
+    cache?: AutolinkCache;
+}
+declare class AutolinkClient {
+    readonly inventory: InventoryResource;
+    readonly inquiries: InquiriesResource;
+    readonly profile: ProfileResource;
+    readonly articles: ArticlesResource;
+    readonly integration: IntegrationResource;
+    constructor(config: AutolinkClientConfig);
+}
+
+declare class AutolinkError extends Error {
+    readonly requestId: string;
+    readonly code: string;
+    constructor(message: string, code: string, requestId: string);
+}
+declare class AutolinkAuthError extends AutolinkError {
+    constructor(message: string, requestId: string);
+}
+declare class AutolinkForbiddenError extends AutolinkError {
+    constructor(message: string, requestId: string);
+}
+declare class AutolinkNotFoundError extends AutolinkError {
+    constructor(message: string, requestId: string);
+}
+declare class AutolinkValidationError extends AutolinkError {
+    readonly fields: Record<string, string[]>;
+    constructor(message: string, requestId: string, fields?: Record<string, string[]>);
+}
+declare class AutolinkRateLimitError extends AutolinkError {
+    readonly retryAfter: number;
+    constructor(message: string, requestId: string, retryAfter: number);
+}
+declare class AutolinkNetworkError extends AutolinkError {
+    readonly cause: Error;
+    constructor(message: string, cause: Error);
+}
+
+declare const GATEWAY_BASE_URL = "https://gateway.autolink.ke";
+declare const GATEWAY_URL = "https://gateway.autolink.ke/sdk/v1";
+declare const SDK_VERSION = "0.1.0";
+
+/** Unwraps a GatewayEnvelope and returns the data directly */
+declare function unwrap<T>(envelope: GatewayEnvelope<T>): T;
+/** Returns field-level validation errors for a given field name */
+declare function getFieldErrors(error: AutolinkValidationError, field: string): string[];
+
+export { type ArticleListFilters, type AutolinkArticle, AutolinkAuthError, type AutolinkCache, AutolinkClient, type AutolinkClientConfig, AutolinkError, AutolinkForbiddenError, type AutolinkInquiry, type AutolinkInquiryPayload, AutolinkNetworkError, AutolinkNotFoundError, type AutolinkProfile, AutolinkRateLimitError, AutolinkValidationError, type AutolinkVehicle, type CoverImageVariants, type FilterOptions, GATEWAY_BASE_URL, GATEWAY_URL, type GatewayEnvelope, type GatewayMeta, type GatewayPagination, type IntegrationStatus, type InventoryListFilters, MemoryCache, SDK_VERSION, type StockStatus, type VehicleCondition, type VehicleDealer, type VehiclePhoto, getFieldErrors, unwrap };