harvester_sdk 1.0.1

package/dist/types.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAllowedEntitiesForPlatform = exports.zodDataSchema = exports.zodGeoSelectionSchema = exports.zodGeoSchema = exports.zodSourceSchema = exports.zodSourceGroupSchema = exports.zodRegionSchema = exports.generalStatusList = exports.zodSourceStatusList = exports.platformEntityMap = exports.entityTypesList = exports.platformsList = void 0;
+const zod_1 = require("zod");
+exports.platformsList = [
+    'telegram',
+    'facebook',
+    'instagram',
+    'tiktok',
+    'website',
+];
+exports.entityTypesList = ['profile', 'group', 'page', 'channel', 'hashtag', 'website'];
+// Platform-specific entity mappings
+exports.platformEntityMap = {
+    telegram: ['channel', 'group'],
+    facebook: ['profile', 'page', 'group'],
+    instagram: ['profile', 'hashtag'],
+    tiktok: ['profile', 'hashtag'],
+    website: ['website'],
+};
+exports.zodSourceStatusList = [
+    'active',
+    'pending',
+    'inactive',
+    'requested', // sources that are under review
+];
+exports.generalStatusList = ['active', 'inactive'];
+exports.zodRegionSchema = zod_1.z.object({
+    _id: zod_1.z.string().optional(),
+    name: zod_1.z.string(),
+    slug: zod_1.z.string(),
+    legend: zod_1.z.string().optional(),
+    created_at: zod_1.z.number().optional(),
+    updated_at: zod_1.z.number().optional(), // last update date
+});
+exports.zodSourceGroupSchema = zod_1.z.object({
+    _id: zod_1.z.string().optional(),
+    name: zod_1.z.string(),
+    description: zod_1.z.string().optional(),
+    platform: zod_1.z.enum(exports.platformsList),
+    region_id: zod_1.z.string().optional(),
+    max_active_sources: zod_1.z.number().optional(),
+    created_at: zod_1.z.number().optional(),
+    updated_at: zod_1.z.number().optional(), // last update date
+});
+exports.zodSourceSchema = zod_1.z
+    .object({
+    _id: zod_1.z.string().optional(),
+    title: zod_1.z.string().optional(),
+    platform: zod_1.z.enum(exports.platformsList),
+    entity: zod_1.z.enum(exports.entityTypesList),
+    public_id: zod_1.z.string().or(zod_1.z.number()).optional(),
+    name: zod_1.z.string(),
+    url: zod_1.z.string().url().optional(),
+    description: zod_1.z.string().optional(),
+    language: zod_1.z.string().optional(),
+    tags: zod_1.z.array(zod_1.z.string()).optional(),
+    status: zod_1.z.enum(exports.zodSourceStatusList),
+    is_public: zod_1.z.boolean().default(true),
+    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
+    created_at: zod_1.z.number().optional(),
+    updated_at: zod_1.z.number().optional(),
+    region_id: zod_1.z.string().optional(),
+    group_id: zod_1.z.string().optional(),
+    requested_by: zod_1.z
+        .object({
+        user_id: zod_1.z.string().optional(),
+        username: zod_1.z.string().optional(),
+        full_name: zod_1.z.string().optional(),
+        email: zod_1.z.string().optional(),
+        requested_at: zod_1.z.number().optional(),
+    })
+        .optional(),
+    notes: zod_1.z.string().optional(), // internal notes about the source
+})
+    .refine((data) => {
+    const allowedEntities = exports.platformEntityMap[data.platform];
+    return allowedEntities.includes(data.entity);
+}, (data) => ({
+    message: `Entity "${data.entity}" is not valid for platform "${data.platform}". Allowed entities: ${exports.platformEntityMap[data.platform].join(', ')}`,
+    path: ['entity'],
+}));
+exports.zodGeoSchema = zod_1.z.object({
+    _id: zod_1.z.string().optional(),
+    geo_text: zod_1.z.string().optional(),
+    timestamp: zod_1.z.number().optional(),
+    count: zod_1.z.number().optional(),
+    region: zod_1.z.string().optional(),
+    subscribers: zod_1.z.array(zod_1.z.string()).optional(),
+    is_used: zod_1.z.boolean().optional().default(false), // true if this geo is used in any source
+});
+exports.zodGeoSelectionSchema = zod_1.z.object({
+    _id: zod_1.z.string().optional(),
+    title: zod_1.z.string().optional(),
+    description: zod_1.z.string().optional(),
+    type: zod_1.z.string().optional(),
+    geos: zod_1.z.array(zod_1.z.string()).optional(),
+    region: zod_1.z.string().optional(),
+    created_at: zod_1.z.number().optional(),
+    updated_at: zod_1.z.number().optional(), // last update date
+});
+exports.zodDataSchema = zod_1.z.object({
+    // Filterable fields
+    text_geo: zod_1.z.array(zod_1.z.string()),
+    timestamp: zod_1.z.number(),
+    platform: zod_1.z.enum(exports.platformsList),
+    source_region: zod_1.z.string().optional(),
+    _id: zod_1.z.string().optional(),
+    source_id: zod_1.z.string().or(zod_1.z.number()),
+    source_public_id: zod_1.z.string().or(zod_1.z.number()),
+    source_name: zod_1.z.string(),
+    platform_id: zod_1.z.string().or(zod_1.z.number()),
+    original_text_id: zod_1.z.string().or(zod_1.z.number()),
+    original_text: zod_1.z.string().optional(),
+    translated_text: zod_1.z.string().optional(),
+    language: zod_1.z.string().optional(),
+    is_reply: zod_1.z.boolean().optional(),
+    reply_to_message_id: zod_1.z.string().or(zod_1.z.number()).optional(),
+    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
+    created_at: zod_1.z.number(),
+    updated_at: zod_1.z.number(),
+    media: zod_1.z
+        .array(zod_1.z.object({
+        type: zod_1.z.enum(['image', 'video', 'audio', 'link']),
+        url: zod_1.z.string().url(),
+        caption: zod_1.z.string().optional(),
+    }))
+        .optional(),
+    author: zod_1.z.string().optional(),
+    replies: zod_1.z.any().optional(),
+    entities: zod_1.z.any().optional(),
+    author_username: zod_1.z.string().optional(),
+    author_id: zod_1.z.string().optional(),
+    group_id: zod_1.z.string().optional(), // e.g., 'default_pipeline'
+});
+// Helper function to get allowed entities for a platform
+const getAllowedEntitiesForPlatform = (platform) => {
+    return exports.platformEntityMap[platform];
+};
+exports.getAllowedEntitiesForPlatform = getAllowedEntitiesForPlatform;

package/index.ts

@@ -0,0 +1,306 @@
+// Export types for consumers
+export * from './types';
+
+import { Schema } from 'mongoose';
+import { 
+  generalStatusList, 
+  platformsList, 
+  entityTypesList,
+  zodSourceStatusList 
+} from './types';
+
+export const MongoDataSchema = new Schema(
+  {
+    source_id: { type: Schema.Types.Mixed, required: true }, // reference to Source _id
+    source_public_id: { type: Schema.Types.Mixed }, // e.g., 'telegram:1234567890' (message_id)
+    source_name: { type: String, required: true }, // e.g., 'Telegram Channel Name'
+    platform_id: { type: Schema.Types.Mixed }, // channel_id reference to Source source_id
+    platform: {
+      type: String,
+      enum: platformsList,
+      required: true,
+    }, // e.g., 'telegram', 'facebook'
+    original_text_id: { type: Schema.Types.Mixed }, // message_id
+    original_text: { type: String }, // original text content
+    translated_text: { type: String }, // translated text if available
+    timestamp: { type: Number, required: true }, // date in milliseconds
+    language: { type: String },
+    text_geo: { type: [String], default: [] }, // e.g., ["sinjil", "ramallah", "west bank"]
+    source_geo: { type: String }, // e.g., 'hebron'
+    is_reply: { type: Boolean }, // true if this text is a reply to another text
+    reply_to_message_id: { type: Schema.Types.Mixed },
+    metadata: { type: Object }, // platform-specific fields
+    created_at: { type: Number, default: Date.now },
+    updated_at: { type: Number, default: Date.now },
+    media: {
+      type: [
+        {
+          type: { type: String, enum: ['image', 'video', 'audio', 'link'] },
+          url: { type: String },
+          caption: { type: String },
+        },
+      ],
+    }, // media attachments
+    author: { type: String }, // e.g., author name or ID
+    replies: { type: Schema.Types.Mixed }, // array of reply texts or IDs
+    entities: { type: Schema.Types.Mixed }, // array of entities
+    author_username: { type: String }, // e.g., author username
+    author_id: { type: String }, // e.g., author ID
+    pipeline_name: { type: String }, // e.g., 'default_pipeline'
+    source_region: { type: String }, // e.g., "New York", "California"
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+export const MongoInstructionsSchema = new Schema(
+  {
+    user_id: { type: String, required: true },
+    prompt: { type: String },
+    created_at: { type: Number, default: Date.now },
+    updated_at: { type: Number, default: Date.now },
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+export const MongoRegionSchema = new Schema(
+  {
+    name: { type: String, required: true }, // e.g., "New York"
+    slug: { type: String, required: true }, // e.g., "new-york"
+    legend: { type: String }, // e.g., legend for maps
+    created_at: { type: Number, default: Date.now }, // creation date
+    updated_at: { type: Number, default: Date.now }, // last update date
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+export const MongoSourceGroupSchema = new Schema(
+  {
+    name: { type: String, required: true }, // e.g., "Group Name"
+    description: { type: String }, // e.g., "Description of the group"
+    platform: {
+      type: String,
+      enum: platformsList,
+      required: true,
+    },
+    region_id: { type: String }, // e.g., region ID
+    max_active_sources: { type: Number }, // e.g., maximum number of active sources allowed
+    created_at: { type: Number, default: Date.now }, // creation date
+    updated_at: { type: Number, default: Date.now }, // last update date
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+export const MongoSourceSchema = new Schema(
+  {
+    title: { type: String }, // e.g., 'Telegram Channel Name'
+    platform: {
+      type: String,
+      enum: platformsList,
+      required: true,
+    },
+    entity: {
+      type: String,
+      enum: entityTypesList,
+      required: true,
+    }, // e.g., 'channel', 'group', 'page', 'profile', 'hashtag'
+    public_id: { type: Schema.Types.Mixed }, // e.g., '@telegram_channel_id'
+    name: { type: String, required: true }, // e.g., 'Telegram Channel Name'
+    url: { type: String }, // e.g., 'https://t.me/telegram_channel_name'
+    description: { type: String }, // e.g., 'A channel about news and updates'
+    language: { type: String },
+    tags: { type: [String], default: [] }, // array of tags
+    status: {
+      type: String,
+      enum: zodSourceStatusList,
+      default: 'pending',
+    }, // INDEX
+    is_public: { type: Boolean, default: true }, // true if the source is public
+    metadata: { type: Object, default: {} }, // flexible per platform
+    created_at: { type: Number, default: Date.now },
+    updated_at: { type: Number, default: Date.now },
+    region_id: { type: String }, // e.g., region ID
+    group_id: { type: String }, // e.g., source group ID
+    requested_by: {
+      type: {
+        user_id: { type: String },
+        username: { type: String },
+        full_name: { type: String },
+        email: { type: String },
+        requested_at: { type: Number },
+      },
+      default: undefined,
+    }, // user who requested this source
+    notes: { type: String }, // internal notes about the source
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+export const MongoQuerySchema = new Schema(
+  {
+    title: { type: String }, // e.g., 'Search Query'
+    query: { type: String }, // search query includes geo information where it should be extracted with LLM
+    sources: { type: [String] }, // array of source _id strings
+    geos: { type: [String], required: true }, // array of geo strings
+    geos_ids: { type: [String], required: true }, // array of geo _id strings
+    time_range: {
+      type: Schema.Types.Mixed, // can be relative or absolute time range
+      required: true,
+    },
+    user_id: { type: String, required: true }, // user identifier
+    user_instructions: { type: String }, // optional user instructions for the query
+    user_time_zone: { type: String }, // user's timezone
+    timestamp: { type: Number, default: Date.now }, // creation date
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+export const MongoUserSettingsSchema = new Schema(
+  {
+    sources: { type: [String] }, // array of source _id strings
+    geos: { type: [String], default: [] }, // array of geo strings
+    time_range: {
+      type: Schema.Types.Mixed,
+    },
+    user_id: { type: String, required: true },
+    thread_id: { type: String },
+    instructions: { type: String }, // optional user instructions for the query
+    has_jobs_access: { type: Boolean, default: false }, // true if the user has access to jobs
+    active_jobs_limit: { type: Number, default: 5 }, // maximum number of active jobs allowed
+    created_at: { type: Date, default: Date.now }, // creation date
+    updated_at: { type: Date, default: Date.now }, // last update date
+    status: {
+      type: String,
+      enum: generalStatusList,
+      default: 'active',
+    }, // status of the user
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+export const MongoConversationSchema = new Schema(
+  {
+    user_id: { type: String, required: true }, // user identifier
+    title: { type: String }, // optional title for the conversation
+    thread_id: { type: String }, // thread ID for the conversation
+    status: {
+      type: String,
+      enum: generalStatusList,
+      default: 'active',
+    }, // status of the conversation
+    created_at: { type: Date, default: Date.now }, // creation date
+    updated_at: { type: Date, default: Date.now }, // last update date
+    is_job: { type: Boolean, default: false }, // true if this is a job conversation
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+export const MongoJobSchema = new Schema(
+  {
+    user_id: { type: String, required: true }, // user identifier
+    job_name: { type: String, required: true }, // name of the automation job
+    job_description: { type: String }, // description of the job
+    status: {
+      type: String,
+      enum: generalStatusList,
+      default: 'active',
+    }, // status of the job
+    created_at: { type: Number, default: Date.now }, // creation date
+    updated_at: { type: Number, default: Date.now }, // last update date
+    schedule: { type: String }, // cron schedule for the job
+    schedule_text: { type: String }, // cron schedule in free-text format
+    active_until: { type: Number || undefined }, // optional date until which the job is active
+    query: { type: Schema.Types.Mixed, required: true }, // query associated with the job
+    conversation_id: { type: String }, // optional conversation ID for the job
+    thread_id: { type: String }, // thread ID for the job
+    time_zone: { type: String }, // optional timezone for the job
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+export const MongoGeoSchema = new Schema(
+  {
+    geo_text: { type: String }, // e.g., "New York, USA"
+    timestamp: { type: Number }, // e.g., 1751210833000
+    count: { type: Number }, // e.g., 42
+    region: { type: String }, // e.g., "New York", "California"
+    subscribers: { type: [String], default: [] }, // array of user IDs who subscribed to this geo
+    is_used: { type: Boolean, default: false }, // true if this geo is used in any source
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+export const MongoGeoSelectionSchema = new Schema(
+  {
+    title: { type: String }, // e.g., "New York, USA"
+    description: { type: String }, // e.g., "A city in the USA"
+    type: { type: String }, // e.g., "city", "region", "country"
+    geos: { type: [String], default: [] }, // e.g., ["New York", "Los Angeles"]
+    region: { type: String }, // e.g., "New York", "California"
+    created_at: { type: Number }, // creation date
+    updated_at: { type: Number }, // last update date
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+export const MongoApiKeySchema = new Schema(
+  {
+    user_id: { type: String, required: true }, // user identifier
+    api_key: { type: String, required: true }, // API key
+    created_at: { type: Number, default: Date.now }, // creation date
+    updated_at: { type: Number, default: Date.now }, // last update date
+    status: {
+      type: String,
+      enum: generalStatusList,
+      default: 'active',
+    }, // status of the API key
+  },
+  {
+    versionKey: false,
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "harvester_sdk",
+  "version": "1.0.1",
+  "description": "SDK for interacting with the Harvester API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "url": "git+https://github.com/badgerdefense/harvester.sdk.git",
+    "type": "git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublish": "npm run build"
+  },
+  "keywords": [
+    "asfur",
+    "sdk",
+    "api"
+  ],
+  "author": "deerland",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "jest": "^29.5.0",
+    "typescript": "^4.9.5"
+  },
+  "dependencies": {
+    "axios": "^1.9.0",
+    "mongoose": "^8.16.4",
+    "zod": "^3.25.76"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "es2018",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["index.ts", "types.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/types.ts

@@ -0,0 +1,177 @@
+import { object, pipeline, z } from 'zod';
+
+export const platformsList = [
+  'telegram',
+  'facebook',
+  'instagram',
+  'tiktok',
+  'website',
+] as const;
+
+export const entityTypesList = ['profile', 'group', 'page', 'channel', 'hashtag', 'website'] as const;
+
+// Platform-specific entity mappings
+export const platformEntityMap = {
+  telegram: ['channel', 'group'],
+  facebook: ['profile', 'page', 'group'],
+  instagram: ['profile', 'hashtag'],
+  tiktok: ['profile', 'hashtag'],
+  website: ['website'],
+} as const;
+
+export const zodSourceStatusList = [
+  'active', // active and approved sources
+  'pending', // sources that are pending approval
+  'inactive', // sources that are inactive
+  'requested', // sources that are under review
+] as const;
+
+export const generalStatusList = ['active', 'inactive'] as const;
+
+export const zodRegionSchema = z.object({
+  _id: z.string().optional(),
+  name: z.string(), // e.g., "New York"
+  slug: z.string(), // e.g., "new-york"
+  legend: z.string().optional(), // e.g., legend for maps
+  created_at: z.number().optional(), // creation date
+  updated_at: z.number().optional(), // last update date
+});
+
+export const zodSourceGroupSchema = z.object({
+  _id: z.string().optional(),
+  name: z.string(), // e.g., "Group Name"
+  description: z.string().optional(), // e.g., "Description of the group"
+  platform: z.enum(platformsList), // e.g., array of resource IDs
+  region_id: z.string().optional(), // e.g., region ID
+  max_active_sources: z.number().optional(), // e.g., maximum number of active sources allowed
+  created_at: z.number().optional(), // creation date
+  updated_at: z.number().optional(), // last update date
+});
+
+export const zodSourceSchema = z
+  .object({
+    _id: z.string().optional(),
+    title: z.string().optional(), // e.g., 'Telegram Channel Name'
+    platform: z.enum(platformsList), // e.g., 'telegram', 'facebook'
+    entity: z.enum(entityTypesList), // e.g., 'channel', 'group', 'page', 'profile', 'hashtag'
+    public_id: z.string().or(z.number()).optional(), // e.g., '@telegram_channel_id'
+    name: z.string(), // e.g., 'Telegram Channel Name'
+    url: z.string().url().optional(), // e.g., 'https://t.me/telegram_channel_name'
+    description: z.string().optional(), // e.g., 'A channel about news and updates'
+    language: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    status: z.enum(zodSourceStatusList), // INDEX
+    is_public: z.boolean().default(true), // true if the source is public
+    metadata: z.record(z.string(), z.any()).optional(), // flexible per platform
+    created_at: z.number().optional(),
+    updated_at: z.number().optional(),
+    region_id: z.string().optional(), // e.g., region ID
+    group_id: z.string().optional(), // e.g., source group ID
+    requested_by: z
+      .object({
+        user_id: z.string().optional(),
+        username: z.string().optional(),
+        full_name: z.string().optional(),
+        email: z.string().optional(),
+        requested_at: z.number().optional(),
+      })
+      .optional(), // user who requested this source
+    notes: z.string().optional(), // internal notes about the source
+  })
+  .refine(
+    (data) => {
+      const allowedEntities = platformEntityMap[data.platform] as readonly string[];
+      return allowedEntities.includes(data.entity);
+    },
+    (data) => ({
+      message: `Entity "${data.entity}" is not valid for platform "${data.platform}". Allowed entities: ${platformEntityMap[data.platform].join(', ')}`,
+      path: ['entity'],
+    })
+  );
+
+export const zodGeoSchema = z.object({
+  _id: z.string().optional(),
+  geo_text: z.string().optional(), // e.g., "New York, USA"
+  timestamp: z.number().optional(), // e.g., 1751210833000
+  count: z.number().optional(), // e.g., 42
+  region: z.string().optional(), // e.g., "New York", "California"
+  subscribers: z.array(z.string()).optional(), // array of user IDs who subscribed to this geo
+  is_used: z.boolean().optional().default(false), // true if this geo is used in any source
+});
+
+export const zodGeoSelectionSchema = z.object({
+  _id: z.string().optional(),
+  title: z.string().optional(), // e.g., "New York, USA"
+  description: z.string().optional(), // e.g., "A city in the USA"
+  type: z.string().optional(), // e.g., "city", "region", "country"
+  geos: z.array(z.string()).optional(), // e.g., ["New York", "Los Angeles"]
+  region: z.string().optional(), // e.g., "New York", "California"
+  created_at: z.number().optional(), // creation date
+  updated_at: z.number().optional(), // last update date
+});
+
+export const zodDataSchema = z.object({
+  // Filterable fields
+  text_geo: z.array(z.string()), // INDEX - e.g., ["sinjil", "ramallah", "west bank"]
+  timestamp: z.number(), // INDEX - date in milliseconds - e.g., 1751210833000
+  platform: z.enum(platformsList), // e.g., 'telegram', 'facebook'
+  source_region: z.string().optional(), // e.g., 'hebron'
+  _id: z.string().optional(),
+  source_id: z.string().or(z.number()), // INDEX - reference to Source _id (e.g., '60c72b2f9b1e8d3f4c8b4567')
+  source_public_id: z.string().or(z.number()), // e.g., 'telegram:1234567890' (message_id)
+  source_name: z.string(), // e.g., 'Telegram Channel Name'
+  platform_id: z.string().or(z.number()), // channel_id reference to Source source_id
+  original_text_id: z.string().or(z.number()), // message_id
+  original_text: z.string().optional(), // original text content
+  translated_text: z.string().optional(), // translated text if available - most of the time it will be translated to English
+  language: z.string().optional(),
+  is_reply: z.boolean().optional(), // true if this text is a reply to another text
+  reply_to_message_id: z.string().or(z.number()).optional(),
+  metadata: z.record(z.string(), z.any()).optional(), // platform-specific fields
+  created_at: z.number(),
+  updated_at: z.number(),
+  media: z
+    .array(
+      z.object({
+        type: z.enum(['image', 'video', 'audio', 'link']),
+        url: z.string().url(),
+        caption: z.string().optional(),
+      })
+    )
+    .optional(), // media attachments
+  author: z.string().optional(), // e.g., author name or ID
+  replies: z.any().optional(), // array of reply texts or IDs
+  entities: z.any().optional(), // array of reply texts or IDs
+  author_username: z.string().optional(), // e.g., author username
+  author_id: z.string().optional(), // e.g., author ID
+  group_id: z.string().optional(), // e.g., 'default_pipeline'
+});
+
+/**
+ * 'approved' - active and approved sources,
+ * 'back_to_business' - sources that were paused and now resumed,
+ * 'pending' - sources that are pending approval,
+ * 'inactive' - sources that are inactive,
+ * 'in_review' - sources that are under review
+ */
+export type RegionType = z.infer<typeof zodRegionSchema>;
+export type SourceGroupType = z.infer<typeof zodSourceGroupSchema>;
+export type SourceType = z.infer<typeof zodSourceSchema>;
+export type DataType = z.infer<typeof zodDataSchema>;
+export type StatusType = (typeof zodSourceStatusList)[number];
+export type TimeRangeTypeLiteral = 'relative' | 'absolute';
+export type AddSourceToReviewType = Pick<
+  SourceType,
+  'platform' | 'url' | 'description'
+> & Partial<Pick<SourceType, 'public_id'>>;
+
+export type GeoType = z.infer<typeof zodGeoSchema>;
+export type GeoSelectionType = z.infer<typeof zodGeoSelectionSchema>;
+
+// Helper type to get allowed entities for a specific platform
+export type PlatformEntityType<T extends typeof platformsList[number]> = typeof platformEntityMap[T][number];
+
+// Helper function to get allowed entities for a platform
+export const getAllowedEntitiesForPlatform = (platform: typeof platformsList[number]) => {
+  return platformEntityMap[platform];
+};