harvester_sdk 1.0.23 → 1.0.25

package/dist/index.d.ts

@@ -24,6 +24,8 @@
 /// <reference types="mongoose/types/inferschematype" />
 /// <reference types="mongoose/types/inferrawdoctype" />
 export * from './types';
+export * from './sdk';
+export { HarvesterSDK, createHarvesterSDK, HarvesterSDKError } from './sdk';
 import { Schema } from 'mongoose';
 export declare const MongoDataSchema: Schema<any, import("mongoose").Model<any, any, any, any, any, any>, {}, {}, {}, {}, {
     versionKey: false;

package/dist/index.js

@@ -14,9 +14,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MongoApiKeySchema = exports.MongoGeoSelectionSchema = exports.MongoGeoSchema = exports.MongoSourceSchema = exports.MongoSourceGroupSchema = exports.MongoRegionSchema = exports.MongoDataSchema = void 0;
+exports.MongoApiKeySchema = exports.MongoGeoSelectionSchema = exports.MongoGeoSchema = exports.MongoSourceSchema = exports.MongoSourceGroupSchema = exports.MongoRegionSchema = exports.MongoDataSchema = exports.HarvesterSDKError = exports.createHarvesterSDK = exports.HarvesterSDK = void 0;
 // Export types for consumers
 __exportStar(require("./types"), exports);
+// Export SDK
+__exportStar(require("./sdk"), exports);
+var sdk_1 = require("./sdk");
+Object.defineProperty(exports, "HarvesterSDK", { enumerable: true, get: function () { return sdk_1.HarvesterSDK; } });
+Object.defineProperty(exports, "createHarvesterSDK", { enumerable: true, get: function () { return sdk_1.createHarvesterSDK; } });
+Object.defineProperty(exports, "HarvesterSDKError", { enumerable: true, get: function () { return sdk_1.HarvesterSDKError; } });
 const mongoose_1 = require("mongoose");
 const types_1 = require("./types");
 exports.MongoDataSchema = new mongoose_1.Schema({

package/dist/sdk.d.ts

@@ -0,0 +1,294 @@
+import { AxiosRequestConfig } from 'axios';
+import { RegionType, GeoType, DataType, platformsList } from './types';
+export interface HarvesterSDKConfig {
+    baseUrl: string;
+    apiKey?: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+}
+export interface TimeRange {
+    start: number;
+    end: number;
+}
+export interface RelativeTimeRange {
+    value: number;
+    unit: 'minutes' | 'hours' | 'days' | 'weeks' | 'months';
+}
+export type Platform = (typeof platformsList)[number];
+export interface PaginationParams {
+    page?: number;
+    limit?: number;
+    sort_by?: string;
+    sort_order?: 'asc' | 'desc';
+}
+export interface GetRegionsParams extends PaginationParams {
+    status?: 'active' | 'inactive' | 'deleted';
+    search?: string;
+}
+export interface GetGeosParams extends PaginationParams {
+    region_id?: string;
+    region?: string;
+    is_used?: boolean;
+    search?: string;
+}
+export interface GetDataParams extends PaginationParams {
+    region_id?: string;
+    region_ids?: string[];
+    time_range?: TimeRange;
+    relative_time?: RelativeTimeRange;
+    platform?: Platform;
+    platforms?: Platform[];
+    source_id?: string;
+    source_ids?: string[];
+    source_group_id?: string;
+    data_geo?: string[];
+    source_dominant_geos?: string[];
+    data_original_type?: string;
+    data_language?: string;
+    data_sentiment?: 'positive' | 'negative' | 'neutral' | 'mixed';
+    search?: string;
+    processing_status?: 'raw' | 'processed' | 'analyzed' | 'error';
+    fields?: string[];
+    exclude_fields?: string[];
+}
+export interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        total_pages: number;
+        has_next: boolean;
+        has_prev: boolean;
+    };
+}
+export interface SDKResponse<T> {
+    success: boolean;
+    data: T;
+    error?: string;
+    message?: string;
+}
+/**
+ * Harvester SDK - Client for interacting with the Harvester API
+ *
+ * @example
+ * ```typescript
+ * const harvester = new HarvesterSDK({
+ *   baseUrl: 'https://api.harvester.io',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * // Get all regions
+ * const regions = await harvester.getRegions();
+ *
+ * // Get geos by region
+ * const geos = await harvester.getGeosByRegion('region-id');
+ *
+ * // Get data with filters
+ * const data = await harvester.getData({
+ *   region_id: 'region-id',
+ *   platform: 'telegram',
+ *   time_range: { start: Date.now() - 86400000, end: Date.now() }
+ * });
+ * ```
+ */
+export declare class HarvesterSDK {
+    private client;
+    private config;
+    constructor(config: HarvesterSDKConfig);
+    /**
+     * Set or update the API key
+     */
+    setApiKey(apiKey: string): void;
+    /**
+     * Make a custom request to the API
+     */
+    request<T>(config: AxiosRequestConfig): Promise<T>;
+    /**
+     * Get all regions
+     *
+     * @param params - Optional filter and pagination parameters
+     * @returns Paginated list of regions
+     *
+     * @example
+     * ```typescript
+     * const regions = await harvester.getRegions({ status: 'active' });
+     * ```
+     */
+    getRegions(params?: GetRegionsParams): Promise<PaginatedResponse<RegionType>>;
+    /**
+     * Get a single region by ID
+     *
+     * @param regionId - The region ID
+     * @returns The region object
+     */
+    getRegionById(regionId: string): Promise<RegionType>;
+    /**
+     * Get a region by slug
+     *
+     * @param slug - The region slug (e.g., 'new-york')
+     * @returns The region object
+     */
+    getRegionBySlug(slug: string): Promise<RegionType>;
+    /**
+     * Get all geographies
+     *
+     * @param params - Optional filter and pagination parameters
+     * @returns Paginated list of geographies
+     */
+    getGeos(params?: GetGeosParams): Promise<PaginatedResponse<GeoType>>;
+    /**
+     * Get geographies by region ID
+     *
+     * @param regionId - The region ID
+     * @param params - Optional pagination parameters
+     * @returns Paginated list of geographies in the region
+     *
+     * @example
+     * ```typescript
+     * const geos = await harvester.getGeosByRegion('region-id', { limit: 50 });
+     * ```
+     */
+    getGeosByRegion(regionId: string, params?: PaginationParams): Promise<PaginatedResponse<GeoType>>;
+    /**
+     * Get a single geography by ID
+     *
+     * @param geoId - The geography ID
+     * @returns The geography object
+     */
+    getGeoById(geoId: string): Promise<GeoType>;
+    /**
+     * Search geographies by text
+     *
+     * @param query - Search query
+     * @param params - Optional filter parameters
+     * @returns Paginated list of matching geographies
+     */
+    searchGeos(query: string, params?: GetGeosParams): Promise<PaginatedResponse<GeoType>>;
+    /**
+     * Get data with filters
+     *
+     * @param params - Filter and pagination parameters
+     * @returns Paginated list of data items
+     *
+     * @example
+     * ```typescript
+     * // Get telegram data from a specific region in the last 24 hours
+     * const data = await harvester.getData({
+     *   region_id: 'region-id',
+     *   platform: 'telegram',
+     *   relative_time: { value: 24, unit: 'hours' }
+     * });
+     * ```
+     */
+    getData(params?: GetDataParams): Promise<PaginatedResponse<DataType>>;
+    /**
+     * Get data by region ID
+     *
+     * @param regionId - The region ID
+     * @param params - Optional filter parameters
+     * @returns Paginated list of data items from the region
+     */
+    getDataByRegion(regionId: string, params?: Omit<GetDataParams, 'region_id'>): Promise<PaginatedResponse<DataType>>;
+    /**
+     * Get data by platform
+     *
+     * @param platform - The platform to filter by
+     * @param params - Optional filter parameters
+     * @returns Paginated list of data items from the platform
+     */
+    getDataByPlatform(platform: Platform, params?: Omit<GetDataParams, 'platform'>): Promise<PaginatedResponse<DataType>>;
+    /**
+     * Get data within a time range
+     *
+     * @param timeRange - The time range (start and end timestamps)
+     * @param params - Optional filter parameters
+     * @returns Paginated list of data items within the time range
+     */
+    getDataByTimeRange(timeRange: TimeRange, params?: Omit<GetDataParams, 'time_range'>): Promise<PaginatedResponse<DataType>>;
+    /**
+     * Get data from relative time (e.g., last 24 hours)
+     *
+     * @param relativeTime - Relative time specification
+     * @param params - Optional filter parameters
+     * @returns Paginated list of data items
+     *
+     * @example
+     * ```typescript
+     * const data = await harvester.getDataFromRelativeTime(
+     *   { value: 7, unit: 'days' },
+     *   { platform: 'telegram' }
+     * );
+     * ```
+     */
+    getDataFromRelativeTime(relativeTime: RelativeTimeRange, params?: Omit<GetDataParams, 'relative_time'>): Promise<PaginatedResponse<DataType>>;
+    /**
+     * Get a single data item by ID
+     *
+     * @param dataId - The data item ID
+     * @returns The data object
+     */
+    getDataById(dataId: string): Promise<DataType>;
+    /**
+     * Search data by text content
+     *
+     * @param query - Search query
+     * @param params - Optional filter parameters
+     * @returns Paginated list of matching data items
+     */
+    searchData(query: string, params?: GetDataParams): Promise<PaginatedResponse<DataType>>;
+    /**
+     * Get data count by filters (without fetching all data)
+     *
+     * @param params - Filter parameters
+     * @returns Count of matching data items
+     */
+    getDataCount(params?: GetDataParams): Promise<number>;
+    /**
+     * Get data aggregated by a field
+     *
+     * @param field - Field to aggregate by (e.g., 'platform', 'source_region_id')
+     * @param params - Optional filter parameters
+     * @returns Aggregation results
+     */
+    getDataAggregation(field: string, params?: GetDataParams): Promise<{
+        _id: string;
+        count: number;
+    }[]>;
+    /**
+     * Convert relative time to absolute time range
+     */
+    relativeToAbsoluteTime(relative: RelativeTimeRange): TimeRange;
+    /**
+     * Build query parameters, removing undefined values
+     */
+    private buildQueryParams;
+    /**
+     * Build data-specific query parameters
+     */
+    private buildDataQueryParams;
+}
+/**
+ * Custom error class for Harvester SDK errors
+ */
+export declare class HarvesterSDKError extends Error {
+    status?: number;
+    data?: any;
+    constructor(message: string, status?: number, data?: any);
+}
+/**
+ * Create a new Harvester SDK instance
+ *
+ * @param config - SDK configuration
+ * @returns HarvesterSDK instance
+ *
+ * @example
+ * ```typescript
+ * const harvester = createHarvesterSDK({
+ *   baseUrl: 'https://api.harvester.io',
+ *   apiKey: 'your-api-key'
+ * });
+ * ```
+ */
+export declare function createHarvesterSDK(config: HarvesterSDKConfig): HarvesterSDK;
+export default HarvesterSDK;

package/dist/sdk.js

@@ -0,0 +1,418 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHarvesterSDK = exports.HarvesterSDKError = exports.HarvesterSDK = void 0;
+const axios_1 = __importDefault(require("axios"));
+/**
+ * Harvester SDK - Client for interacting with the Harvester API
+ *
+ * @example
+ * ```typescript
+ * const harvester = new HarvesterSDK({
+ *   baseUrl: 'https://api.harvester.io',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * // Get all regions
+ * const regions = await harvester.getRegions();
+ *
+ * // Get geos by region
+ * const geos = await harvester.getGeosByRegion('region-id');
+ *
+ * // Get data with filters
+ * const data = await harvester.getData({
+ *   region_id: 'region-id',
+ *   platform: 'telegram',
+ *   time_range: { start: Date.now() - 86400000, end: Date.now() }
+ * });
+ * ```
+ */
+class HarvesterSDK {
+    constructor(config) {
+        this.config = config;
+        this.client = axios_1.default.create({
+            baseURL: config.baseUrl,
+            timeout: config.timeout || 30000,
+            headers: {
+                'Content-Type': 'application/json',
+                ...(config.apiKey && { Authorization: `Bearer ${config.apiKey}` }),
+                ...config.headers,
+            },
+        });
+        // Add response interceptor for error handling
+        this.client.interceptors.response.use((response) => response, (error) => {
+            var _a, _b, _c, _d;
+            const message = ((_b = (_a = error.response) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.message) || error.message;
+            throw new HarvesterSDKError(message, (_c = error.response) === null || _c === void 0 ? void 0 : _c.status, (_d = error.response) === null || _d === void 0 ? void 0 : _d.data);
+        });
+    }
+    /**
+     * Set or update the API key
+     */
+    setApiKey(apiKey) {
+        this.config.apiKey = apiKey;
+        this.client.defaults.headers.common['Authorization'] = `Bearer ${apiKey}`;
+    }
+    /**
+     * Make a custom request to the API
+     */
+    async request(config) {
+        const response = await this.client.request(config);
+        return response.data;
+    }
+    // ============================================
+    // REGIONS
+    // ============================================
+    /**
+     * Get all regions
+     *
+     * @param params - Optional filter and pagination parameters
+     * @returns Paginated list of regions
+     *
+     * @example
+     * ```typescript
+     * const regions = await harvester.getRegions({ status: 'active' });
+     * ```
+     */
+    async getRegions(params) {
+        const response = await this.client.get('/regions', {
+            params: this.buildQueryParams(params),
+        });
+        return response.data;
+    }
+    /**
+     * Get a single region by ID
+     *
+     * @param regionId - The region ID
+     * @returns The region object
+     */
+    async getRegionById(regionId) {
+        const response = await this.client.get(`/regions/${regionId}`);
+        return response.data.data;
+    }
+    /**
+     * Get a region by slug
+     *
+     * @param slug - The region slug (e.g., 'new-york')
+     * @returns The region object
+     */
+    async getRegionBySlug(slug) {
+        const response = await this.client.get(`/regions/slug/${slug}`);
+        return response.data.data;
+    }
+    // ============================================
+    // GEOGRAPHIES
+    // ============================================
+    /**
+     * Get all geographies
+     *
+     * @param params - Optional filter and pagination parameters
+     * @returns Paginated list of geographies
+     */
+    async getGeos(params) {
+        const response = await this.client.get('/geos', {
+            params: this.buildQueryParams(params),
+        });
+        return response.data;
+    }
+    /**
+     * Get geographies by region ID
+     *
+     * @param regionId - The region ID
+     * @param params - Optional pagination parameters
+     * @returns Paginated list of geographies in the region
+     *
+     * @example
+     * ```typescript
+     * const geos = await harvester.getGeosByRegion('region-id', { limit: 50 });
+     * ```
+     */
+    async getGeosByRegion(regionId, params) {
+        const response = await this.client.get(`/regions/${regionId}/geos`, {
+            params: this.buildQueryParams(params),
+        });
+        return response.data;
+    }
+    /**
+     * Get a single geography by ID
+     *
+     * @param geoId - The geography ID
+     * @returns The geography object
+     */
+    async getGeoById(geoId) {
+        const response = await this.client.get(`/geos/${geoId}`);
+        return response.data.data;
+    }
+    /**
+     * Search geographies by text
+     *
+     * @param query - Search query
+     * @param params - Optional filter parameters
+     * @returns Paginated list of matching geographies
+     */
+    async searchGeos(query, params) {
+        const response = await this.client.get('/geos/search', {
+            params: this.buildQueryParams({ ...params, search: query }),
+        });
+        return response.data;
+    }
+    // ============================================
+    // DATA
+    // ============================================
+    /**
+     * Get data with filters
+     *
+     * @param params - Filter and pagination parameters
+     * @returns Paginated list of data items
+     *
+     * @example
+     * ```typescript
+     * // Get telegram data from a specific region in the last 24 hours
+     * const data = await harvester.getData({
+     *   region_id: 'region-id',
+     *   platform: 'telegram',
+     *   relative_time: { value: 24, unit: 'hours' }
+     * });
+     * ```
+     */
+    async getData(params) {
+        const queryParams = this.buildDataQueryParams(params);
+        const response = await this.client.get('/data', {
+            params: queryParams,
+        });
+        return response.data;
+    }
+    /**
+     * Get data by region ID
+     *
+     * @param regionId - The region ID
+     * @param params - Optional filter parameters
+     * @returns Paginated list of data items from the region
+     */
+    async getDataByRegion(regionId, params) {
+        return this.getData({ ...params, region_id: regionId });
+    }
+    /**
+     * Get data by platform
+     *
+     * @param platform - The platform to filter by
+     * @param params - Optional filter parameters
+     * @returns Paginated list of data items from the platform
+     */
+    async getDataByPlatform(platform, params) {
+        return this.getData({ ...params, platform });
+    }
+    /**
+     * Get data within a time range
+     *
+     * @param timeRange - The time range (start and end timestamps)
+     * @param params - Optional filter parameters
+     * @returns Paginated list of data items within the time range
+     */
+    async getDataByTimeRange(timeRange, params) {
+        return this.getData({ ...params, time_range: timeRange });
+    }
+    /**
+     * Get data from relative time (e.g., last 24 hours)
+     *
+     * @param relativeTime - Relative time specification
+     * @param params - Optional filter parameters
+     * @returns Paginated list of data items
+     *
+     * @example
+     * ```typescript
+     * const data = await harvester.getDataFromRelativeTime(
+     *   { value: 7, unit: 'days' },
+     *   { platform: 'telegram' }
+     * );
+     * ```
+     */
+    async getDataFromRelativeTime(relativeTime, params) {
+        return this.getData({ ...params, relative_time: relativeTime });
+    }
+    /**
+     * Get a single data item by ID
+     *
+     * @param dataId - The data item ID
+     * @returns The data object
+     */
+    async getDataById(dataId) {
+        const response = await this.client.get(`/data/${dataId}`);
+        return response.data.data;
+    }
+    /**
+     * Search data by text content
+     *
+     * @param query - Search query
+     * @param params - Optional filter parameters
+     * @returns Paginated list of matching data items
+     */
+    async searchData(query, params) {
+        return this.getData({ ...params, search: query });
+    }
+    /**
+     * Get data count by filters (without fetching all data)
+     *
+     * @param params - Filter parameters
+     * @returns Count of matching data items
+     */
+    async getDataCount(params) {
+        const queryParams = this.buildDataQueryParams(params);
+        const response = await this.client.get('/data/count', {
+            params: queryParams,
+        });
+        return response.data.count;
+    }
+    /**
+     * Get data aggregated by a field
+     *
+     * @param field - Field to aggregate by (e.g., 'platform', 'source_region_id')
+     * @param params - Optional filter parameters
+     * @returns Aggregation results
+     */
+    async getDataAggregation(field, params) {
+        const queryParams = this.buildDataQueryParams(params);
+        const response = await this.client.get(`/data/aggregate/${field}`, { params: queryParams });
+        return response.data.data;
+    }
+    // ============================================
+    // HELPER METHODS
+    // ============================================
+    /**
+     * Convert relative time to absolute time range
+     */
+    relativeToAbsoluteTime(relative) {
+        const now = Date.now();
+        const multipliers = {
+            minutes: 60 * 1000,
+            hours: 60 * 60 * 1000,
+            days: 24 * 60 * 60 * 1000,
+            weeks: 7 * 24 * 60 * 60 * 1000,
+            months: 30 * 24 * 60 * 60 * 1000,
+        };
+        const ms = relative.value * multipliers[relative.unit];
+        return {
+            start: now - ms,
+            end: now,
+        };
+    }
+    /**
+     * Build query parameters, removing undefined values
+     */
+    buildQueryParams(params) {
+        if (!params)
+            return {};
+        const cleaned = {};
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== null) {
+                if (Array.isArray(value)) {
+                    cleaned[key] = value.join(',');
+                }
+                else if (typeof value === 'object') {
+                    cleaned[key] = JSON.stringify(value);
+                }
+                else {
+                    cleaned[key] = value;
+                }
+            }
+        }
+        return cleaned;
+    }
+    /**
+     * Build data-specific query parameters
+     */
+    buildDataQueryParams(params) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        if (!params)
+            return {};
+        const queryParams = {};
+        // Handle time range
+        if (params.time_range) {
+            queryParams.start_time = params.time_range.start;
+            queryParams.end_time = params.time_range.end;
+        }
+        else if (params.relative_time) {
+            const absoluteTime = this.relativeToAbsoluteTime(params.relative_time);
+            queryParams.start_time = absoluteTime.start;
+            queryParams.end_time = absoluteTime.end;
+        }
+        // Handle arrays
+        if ((_a = params.region_ids) === null || _a === void 0 ? void 0 : _a.length) {
+            queryParams.region_ids = params.region_ids.join(',');
+        }
+        if ((_b = params.platforms) === null || _b === void 0 ? void 0 : _b.length) {
+            queryParams.platforms = params.platforms.join(',');
+        }
+        if ((_c = params.source_ids) === null || _c === void 0 ? void 0 : _c.length) {
+            queryParams.source_ids = params.source_ids.join(',');
+        }
+        if ((_d = params.data_geo) === null || _d === void 0 ? void 0 : _d.length) {
+            queryParams.data_geo = params.data_geo.join(',');
+        }
+        if ((_e = params.source_dominant_geos) === null || _e === void 0 ? void 0 : _e.length) {
+            queryParams.source_dominant_geos = params.source_dominant_geos.join(',');
+        }
+        if ((_f = params.fields) === null || _f === void 0 ? void 0 : _f.length) {
+            queryParams.fields = params.fields.join(',');
+        }
+        if ((_g = params.exclude_fields) === null || _g === void 0 ? void 0 : _g.length) {
+            queryParams.exclude_fields = params.exclude_fields.join(',');
+        }
+        // Handle simple parameters
+        const simpleParams = [
+            'region_id',
+            'platform',
+            'source_id',
+            'source_group_id',
+            'data_original_type',
+            'data_language',
+            'data_sentiment',
+            'search',
+            'processing_status',
+            'page',
+            'limit',
+            'sort_by',
+            'sort_order',
+        ];
+        for (const param of simpleParams) {
+            if (params[param] !== undefined) {
+                queryParams[param] = params[param];
+            }
+        }
+        return queryParams;
+    }
+}
+exports.HarvesterSDK = HarvesterSDK;
+/**
+ * Custom error class for Harvester SDK errors
+ */
+class HarvesterSDKError extends Error {
+    constructor(message, status, data) {
+        super(message);
+        this.name = 'HarvesterSDKError';
+        this.status = status;
+        this.data = data;
+    }
+}
+exports.HarvesterSDKError = HarvesterSDKError;
+/**
+ * Create a new Harvester SDK instance
+ *
+ * @param config - SDK configuration
+ * @returns HarvesterSDK instance
+ *
+ * @example
+ * ```typescript
+ * const harvester = createHarvesterSDK({
+ *   baseUrl: 'https://api.harvester.io',
+ *   apiKey: 'your-api-key'
+ * });
+ * ```
+ */
+function createHarvesterSDK(config) {
+    return new HarvesterSDK(config);
+}
+exports.createHarvesterSDK = createHarvesterSDK;
+exports.default = HarvesterSDK;

package/index.ts

@@ -1,6 +1,10 @@
 // Export types for consumers
 export * from './types';
 
+// Export SDK
+export * from './sdk';
+export { HarvesterSDK, createHarvesterSDK, HarvesterSDKError } from './sdk';
+
 import { Schema } from 'mongoose';
 import {
   generalStatusList,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harvester_sdk",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "SDK for interacting with the Harvester API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/sdk.ts

@@ -0,0 +1,558 @@
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+import {
+  RegionType,
+  GeoType,
+  DataType,
+  platformsList,
+} from './types';
+
+// SDK Configuration
+export interface HarvesterSDKConfig {
+  baseUrl: string;
+  apiKey?: string;
+  timeout?: number;
+  headers?: Record<string, string>;
+}
+
+// Query Parameters
+export interface TimeRange {
+  start: number; // Unix timestamp in milliseconds
+  end: number; // Unix timestamp in milliseconds
+}
+
+export interface RelativeTimeRange {
+  value: number;
+  unit: 'minutes' | 'hours' | 'days' | 'weeks' | 'months';
+}
+
+export type Platform = (typeof platformsList)[number];
+
+export interface PaginationParams {
+  page?: number;
+  limit?: number;
+  sort_by?: string;
+  sort_order?: 'asc' | 'desc';
+}
+
+export interface GetRegionsParams extends PaginationParams {
+  status?: 'active' | 'inactive' | 'deleted';
+  search?: string;
+}
+
+export interface GetGeosParams extends PaginationParams {
+  region_id?: string;
+  region?: string; // region slug or name
+  is_used?: boolean;
+  search?: string;
+}
+
+export interface GetDataParams extends PaginationParams {
+  // Region filters
+  region_id?: string;
+  region_ids?: string[];
+  
+  // Time filters
+  time_range?: TimeRange;
+  relative_time?: RelativeTimeRange;
+  
+  // Platform filters
+  platform?: Platform;
+  platforms?: Platform[];
+  
+  // Source filters
+  source_id?: string;
+  source_ids?: string[];
+  source_group_id?: string;
+  
+  // Geo filters
+  data_geo?: string[];
+  source_dominant_geos?: string[];
+  
+  // Content filters
+  data_original_type?: string;
+  data_language?: string;
+  data_sentiment?: 'positive' | 'negative' | 'neutral' | 'mixed';
+  
+  // Text search
+  search?: string;
+  
+  // Processing status
+  processing_status?: 'raw' | 'processed' | 'analyzed' | 'error';
+  
+  // Include/exclude fields
+  fields?: string[];
+  exclude_fields?: string[];
+}
+
+// Response types
+export interface PaginatedResponse<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    total_pages: number;
+    has_next: boolean;
+    has_prev: boolean;
+  };
+}
+
+export interface SDKResponse<T> {
+  success: boolean;
+  data: T;
+  error?: string;
+  message?: string;
+}
+
+/**
+ * Harvester SDK - Client for interacting with the Harvester API
+ * 
+ * @example
+ * ```typescript
+ * const harvester = new HarvesterSDK({
+ *   baseUrl: 'https://api.harvester.io',
+ *   apiKey: 'your-api-key'
+ * });
+ * 
+ * // Get all regions
+ * const regions = await harvester.getRegions();
+ * 
+ * // Get geos by region
+ * const geos = await harvester.getGeosByRegion('region-id');
+ * 
+ * // Get data with filters
+ * const data = await harvester.getData({
+ *   region_id: 'region-id',
+ *   platform: 'telegram',
+ *   time_range: { start: Date.now() - 86400000, end: Date.now() }
+ * });
+ * ```
+ */
+export class HarvesterSDK {
+  private client: AxiosInstance;
+  private config: HarvesterSDKConfig;
+
+  constructor(config: HarvesterSDKConfig) {
+    this.config = config;
+    this.client = axios.create({
+      baseURL: config.baseUrl,
+      timeout: config.timeout || 30000,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(config.apiKey && { Authorization: `Bearer ${config.apiKey}` }),
+        ...config.headers,
+      },
+    });
+
+    // Add response interceptor for error handling
+    this.client.interceptors.response.use(
+      (response) => response,
+      (error) => {
+        const message = error.response?.data?.message || error.message;
+        throw new HarvesterSDKError(message, error.response?.status, error.response?.data);
+      }
+    );
+  }
+
+  /**
+   * Set or update the API key
+   */
+  setApiKey(apiKey: string): void {
+    this.config.apiKey = apiKey;
+    this.client.defaults.headers.common['Authorization'] = `Bearer ${apiKey}`;
+  }
+
+  /**
+   * Make a custom request to the API
+   */
+  async request<T>(config: AxiosRequestConfig): Promise<T> {
+    const response = await this.client.request<T>(config);
+    return response.data;
+  }
+
+  // ============================================
+  // REGIONS
+  // ============================================
+
+  /**
+   * Get all regions
+   * 
+   * @param params - Optional filter and pagination parameters
+   * @returns Paginated list of regions
+   * 
+   * @example
+   * ```typescript
+   * const regions = await harvester.getRegions({ status: 'active' });
+   * ```
+   */
+  async getRegions(params?: GetRegionsParams): Promise<PaginatedResponse<RegionType>> {
+    const response = await this.client.get<PaginatedResponse<RegionType>>('/regions', {
+      params: this.buildQueryParams(params),
+    });
+    return response.data;
+  }
+
+  /**
+   * Get a single region by ID
+   * 
+   * @param regionId - The region ID
+   * @returns The region object
+   */
+  async getRegionById(regionId: string): Promise<RegionType> {
+    const response = await this.client.get<SDKResponse<RegionType>>(`/regions/${regionId}`);
+    return response.data.data;
+  }
+
+  /**
+   * Get a region by slug
+   * 
+   * @param slug - The region slug (e.g., 'new-york')
+   * @returns The region object
+   */
+  async getRegionBySlug(slug: string): Promise<RegionType> {
+    const response = await this.client.get<SDKResponse<RegionType>>(`/regions/slug/${slug}`);
+    return response.data.data;
+  }
+
+  // ============================================
+  // GEOGRAPHIES
+  // ============================================
+
+  /**
+   * Get all geographies
+   * 
+   * @param params - Optional filter and pagination parameters
+   * @returns Paginated list of geographies
+   */
+  async getGeos(params?: GetGeosParams): Promise<PaginatedResponse<GeoType>> {
+    const response = await this.client.get<PaginatedResponse<GeoType>>('/geos', {
+      params: this.buildQueryParams(params),
+    });
+    return response.data;
+  }
+
+  /**
+   * Get geographies by region ID
+   * 
+   * @param regionId - The region ID
+   * @param params - Optional pagination parameters
+   * @returns Paginated list of geographies in the region
+   * 
+   * @example
+   * ```typescript
+   * const geos = await harvester.getGeosByRegion('region-id', { limit: 50 });
+   * ```
+   */
+  async getGeosByRegion(regionId: string, params?: PaginationParams): Promise<PaginatedResponse<GeoType>> {
+    const response = await this.client.get<PaginatedResponse<GeoType>>(`/regions/${regionId}/geos`, {
+      params: this.buildQueryParams(params),
+    });
+    return response.data;
+  }
+
+  /**
+   * Get a single geography by ID
+   * 
+   * @param geoId - The geography ID
+   * @returns The geography object
+   */
+  async getGeoById(geoId: string): Promise<GeoType> {
+    const response = await this.client.get<SDKResponse<GeoType>>(`/geos/${geoId}`);
+    return response.data.data;
+  }
+
+  /**
+   * Search geographies by text
+   * 
+   * @param query - Search query
+   * @param params - Optional filter parameters
+   * @returns Paginated list of matching geographies
+   */
+  async searchGeos(query: string, params?: GetGeosParams): Promise<PaginatedResponse<GeoType>> {
+    const response = await this.client.get<PaginatedResponse<GeoType>>('/geos/search', {
+      params: this.buildQueryParams({ ...params, search: query }),
+    });
+    return response.data;
+  }
+
+  // ============================================
+  // DATA
+  // ============================================
+
+  /**
+   * Get data with filters
+   * 
+   * @param params - Filter and pagination parameters
+   * @returns Paginated list of data items
+   * 
+   * @example
+   * ```typescript
+   * // Get telegram data from a specific region in the last 24 hours
+   * const data = await harvester.getData({
+   *   region_id: 'region-id',
+   *   platform: 'telegram',
+   *   relative_time: { value: 24, unit: 'hours' }
+   * });
+   * ```
+   */
+  async getData(params?: GetDataParams): Promise<PaginatedResponse<DataType>> {
+    const queryParams = this.buildDataQueryParams(params);
+    const response = await this.client.get<PaginatedResponse<DataType>>('/data', {
+      params: queryParams,
+    });
+    return response.data;
+  }
+
+  /**
+   * Get data by region ID
+   * 
+   * @param regionId - The region ID
+   * @param params - Optional filter parameters
+   * @returns Paginated list of data items from the region
+   */
+  async getDataByRegion(regionId: string, params?: Omit<GetDataParams, 'region_id'>): Promise<PaginatedResponse<DataType>> {
+    return this.getData({ ...params, region_id: regionId });
+  }
+
+  /**
+   * Get data by platform
+   * 
+   * @param platform - The platform to filter by
+   * @param params - Optional filter parameters
+   * @returns Paginated list of data items from the platform
+   */
+  async getDataByPlatform(platform: Platform, params?: Omit<GetDataParams, 'platform'>): Promise<PaginatedResponse<DataType>> {
+    return this.getData({ ...params, platform });
+  }
+
+  /**
+   * Get data within a time range
+   * 
+   * @param timeRange - The time range (start and end timestamps)
+   * @param params - Optional filter parameters
+   * @returns Paginated list of data items within the time range
+   */
+  async getDataByTimeRange(timeRange: TimeRange, params?: Omit<GetDataParams, 'time_range'>): Promise<PaginatedResponse<DataType>> {
+    return this.getData({ ...params, time_range: timeRange });
+  }
+
+  /**
+   * Get data from relative time (e.g., last 24 hours)
+   * 
+   * @param relativeTime - Relative time specification
+   * @param params - Optional filter parameters
+   * @returns Paginated list of data items
+   * 
+   * @example
+   * ```typescript
+   * const data = await harvester.getDataFromRelativeTime(
+   *   { value: 7, unit: 'days' },
+   *   { platform: 'telegram' }
+   * );
+   * ```
+   */
+  async getDataFromRelativeTime(relativeTime: RelativeTimeRange, params?: Omit<GetDataParams, 'relative_time'>): Promise<PaginatedResponse<DataType>> {
+    return this.getData({ ...params, relative_time: relativeTime });
+  }
+
+  /**
+   * Get a single data item by ID
+   * 
+   * @param dataId - The data item ID
+   * @returns The data object
+   */
+  async getDataById(dataId: string): Promise<DataType> {
+    const response = await this.client.get<SDKResponse<DataType>>(`/data/${dataId}`);
+    return response.data.data;
+  }
+
+  /**
+   * Search data by text content
+   * 
+   * @param query - Search query
+   * @param params - Optional filter parameters
+   * @returns Paginated list of matching data items
+   */
+  async searchData(query: string, params?: GetDataParams): Promise<PaginatedResponse<DataType>> {
+    return this.getData({ ...params, search: query });
+  }
+
+  /**
+   * Get data count by filters (without fetching all data)
+   * 
+   * @param params - Filter parameters
+   * @returns Count of matching data items
+   */
+  async getDataCount(params?: GetDataParams): Promise<number> {
+    const queryParams = this.buildDataQueryParams(params);
+    const response = await this.client.get<{ count: number }>('/data/count', {
+      params: queryParams,
+    });
+    return response.data.count;
+  }
+
+  /**
+   * Get data aggregated by a field
+   * 
+   * @param field - Field to aggregate by (e.g., 'platform', 'source_region_id')
+   * @param params - Optional filter parameters
+   * @returns Aggregation results
+   */
+  async getDataAggregation(
+    field: string,
+    params?: GetDataParams
+  ): Promise<{ _id: string; count: number }[]> {
+    const queryParams = this.buildDataQueryParams(params);
+    const response = await this.client.get<{ data: { _id: string; count: number }[] }>(
+      `/data/aggregate/${field}`,
+      { params: queryParams }
+    );
+    return response.data.data;
+  }
+
+  // ============================================
+  // HELPER METHODS
+  // ============================================
+
+  /**
+   * Convert relative time to absolute time range
+   */
+  relativeToAbsoluteTime(relative: RelativeTimeRange): TimeRange {
+    const now = Date.now();
+    const multipliers: Record<string, number> = {
+      minutes: 60 * 1000,
+      hours: 60 * 60 * 1000,
+      days: 24 * 60 * 60 * 1000,
+      weeks: 7 * 24 * 60 * 60 * 1000,
+      months: 30 * 24 * 60 * 60 * 1000,
+    };
+    const ms = relative.value * multipliers[relative.unit];
+    return {
+      start: now - ms,
+      end: now,
+    };
+  }
+
+  /**
+   * Build query parameters, removing undefined values
+   */
+  private buildQueryParams(params?: Record<string, any>): Record<string, any> {
+    if (!params) return {};
+    
+    const cleaned: Record<string, any> = {};
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined && value !== null) {
+        if (Array.isArray(value)) {
+          cleaned[key] = value.join(',');
+        } else if (typeof value === 'object') {
+          cleaned[key] = JSON.stringify(value);
+        } else {
+          cleaned[key] = value;
+        }
+      }
+    }
+    return cleaned;
+  }
+
+  /**
+   * Build data-specific query parameters
+   */
+  private buildDataQueryParams(params?: GetDataParams): Record<string, any> {
+    if (!params) return {};
+
+    const queryParams: Record<string, any> = {};
+
+    // Handle time range
+    if (params.time_range) {
+      queryParams.start_time = params.time_range.start;
+      queryParams.end_time = params.time_range.end;
+    } else if (params.relative_time) {
+      const absoluteTime = this.relativeToAbsoluteTime(params.relative_time);
+      queryParams.start_time = absoluteTime.start;
+      queryParams.end_time = absoluteTime.end;
+    }
+
+    // Handle arrays
+    if (params.region_ids?.length) {
+      queryParams.region_ids = params.region_ids.join(',');
+    }
+    if (params.platforms?.length) {
+      queryParams.platforms = params.platforms.join(',');
+    }
+    if (params.source_ids?.length) {
+      queryParams.source_ids = params.source_ids.join(',');
+    }
+    if (params.data_geo?.length) {
+      queryParams.data_geo = params.data_geo.join(',');
+    }
+    if (params.source_dominant_geos?.length) {
+      queryParams.source_dominant_geos = params.source_dominant_geos.join(',');
+    }
+    if (params.fields?.length) {
+      queryParams.fields = params.fields.join(',');
+    }
+    if (params.exclude_fields?.length) {
+      queryParams.exclude_fields = params.exclude_fields.join(',');
+    }
+
+    // Handle simple parameters
+    const simpleParams = [
+      'region_id',
+      'platform',
+      'source_id',
+      'source_group_id',
+      'data_original_type',
+      'data_language',
+      'data_sentiment',
+      'search',
+      'processing_status',
+      'page',
+      'limit',
+      'sort_by',
+      'sort_order',
+    ];
+
+    for (const param of simpleParams) {
+      if (params[param as keyof GetDataParams] !== undefined) {
+        queryParams[param] = params[param as keyof GetDataParams];
+      }
+    }
+
+    return queryParams;
+  }
+}
+
+/**
+ * Custom error class for Harvester SDK errors
+ */
+export class HarvesterSDKError extends Error {
+  status?: number;
+  data?: any;
+
+  constructor(message: string, status?: number, data?: any) {
+    super(message);
+    this.name = 'HarvesterSDKError';
+    this.status = status;
+    this.data = data;
+  }
+}
+
+/**
+ * Create a new Harvester SDK instance
+ * 
+ * @param config - SDK configuration
+ * @returns HarvesterSDK instance
+ * 
+ * @example
+ * ```typescript
+ * const harvester = createHarvesterSDK({
+ *   baseUrl: 'https://api.harvester.io',
+ *   apiKey: 'your-api-key'
+ * });
+ * ```
+ */
+export function createHarvesterSDK(config: HarvesterSDKConfig): HarvesterSDK {
+  return new HarvesterSDK(config);
+}
+
+export default HarvesterSDK;