harvester_sdk 1.0.22 → 1.0.24

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;