@linkt/sdk 0.2.0 → 0.4.0

package/resources/entity.d.mts

@@ -0,0 +1,392 @@
+import { APIResource } from "../core/resource.mjs";
+import * as SheetAPI from "./sheet/sheet.mjs";
+import { APIPromise } from "../core/api-promise.mjs";
+import { RequestOptions } from "../internal/request-options.mjs";
+export declare class Entity extends APIResource {
+    /**
+     * Get a single entity by ID with enrichment.
+     *
+     * Returns the entity with sheet_name, entity_type, and icp_id populated from the
+     * parent sheet.
+     */
+    retrieve(entityID: string, options?: RequestOptions): APIPromise<EntityResponse>;
+    /**
+     * Update entity status or comments.
+     *
+     * Only status and comments can be updated via this endpoint. Use status=null to
+     * clear status, comments=null to clear comments.
+     *
+     * Status must be one of: new, reviewed, passed, contacted, or null.
+     */
+    update(entityID: string, body: EntityUpdateParams, options?: RequestOptions): APIPromise<EntityResponse>;
+    /**
+     * Get paginated list of entities with filtering.
+     *
+     * Supports filtering by:
+     *
+     * - icp_id: Entities in sheets belonging to an ICP
+     * - sheet_id: Entities in a specific sheet
+     * - entity_type: Entities of a specific type (company, person, etc.)
+     * - status: Filter by workflow status (supports multiple:
+     *   ?status=new&status=reviewed) Valid values: new, reviewed, passed, contacted,
+     *   null
+     *
+     * All results include enrichment fields for UI annotations.
+     */
+    list(query?: EntityListParams | null | undefined, options?: RequestOptions): APIPromise<EntityListResponse>;
+    /**
+     * Delete an entity by ID.
+     *
+     * This is a hard delete - the entity will be permanently removed.
+     */
+    delete(entityID: string, options?: RequestOptions): APIPromise<void>;
+    /**
+     * Update status for multiple entities at once.
+     *
+     * Accepts a list of entity IDs and a status value. The status can be:
+     *
+     * - "new", "reviewed", "passed", "contacted" (valid workflow statuses)
+     * - null (to clear the status)
+     *
+     * Returns the count of successfully updated entities and any failed IDs. Entities
+     * may fail to update if they have an invalid ID format or don't exist.
+     *
+     * WHY: Bulk operations enable users to update status for many entities at once
+     * (e.g., mark all search results as "reviewed"), improving workflow efficiency
+     * versus N individual PUT calls. Uses batch_update_by_filter for single database
+     * roundtrip efficiency.
+     */
+    bulkUpdateStatus(body: EntityBulkUpdateStatusParams, options?: RequestOptions): APIPromise<EntityBulkUpdateStatusResponse>;
+    /**
+     * Export entities as CSV.
+     *
+     * Supports two formats:
+     *
+     * **separate** (default):
+     *
+     * - One row per entity
+     * - Standard flat export
+     * - All entity types exported independently
+     *
+     * **combined**:
+     *
+     * - Pre-joined parent-child rows
+     * - Requires icp_id parameter
+     * - Child entity columns appear first, followed by parent columns
+     * - Columns prefixed with entity type (e.g., "Person Name", "Company Industry")
+     * - Parent data repeats for each child (one row per child)
+     * - Orphan parents (no children) appear as rows with empty child columns
+     *
+     * **Excluded Fields** (both formats):
+     *
+     * - id, sheet_id, parent_id, icp_id, entity_type, sheet_name, comments
+     *
+     * **Included Fields**:
+     *
+     * - All data.\* fields (the actual enrichment data)
+     * - status, created_at, updated_at
+     *
+     * **Filtering**:
+     *
+     * - status: Filter by workflow status (supports multiple:
+     *   ?status=new&status=contacted) Valid values: new, reviewed, passed, contacted,
+     *   null
+     *
+     * Args: icp_id: Filter by ICP ID (REQUIRED for format=combined) sheet_id: Filter
+     * by sheet ID entity_type: Filter by entity type (ignored for format=combined)
+     * entity_ids: Export specific entity IDs status: Filter by status values (multiple
+     * allowed) format: Export format - "separate" (default) or "combined"
+     *
+     * Returns: StreamingResponse with CSV content
+     *
+     * Raises: HTTPException 400: format=combined without icp_id, or invalid status
+     * value HTTPException 404: ICP, sheet, or entities not found
+     */
+    export(query?: EntityExportParams | null | undefined, options?: RequestOptions): APIPromise<unknown>;
+    /**
+     * Get entity counts grouped by entity_type.
+     *
+     * Returns the count of entities for each entity_type (company, person, etc.)
+     * across the organization. Supports optional filtering by ICP or status.
+     *
+     * Additional filtering:
+     *
+     * - status: Filter by workflow status (supports multiple:
+     *   ?status=new&status=reviewed) Valid values: new, reviewed, passed, contacted,
+     *   null
+     *
+     * Used by Entity Master List for accurate tab navigation counts.
+     */
+    getCounts(query?: EntityGetCountsParams | null | undefined, options?: RequestOptions): APIPromise<EntityGetCountsResponse>;
+    /**
+     * Search entities by text query.
+     *
+     * Uses MongoDB Atlas Search for fuzzy text matching on entity names and company
+     * fields. Results are sorted by relevance.
+     *
+     * Scope of search determined by filters:
+     *
+     * - sheet_id: Search within specific sheet
+     * - icp_id: Search across ICP sheets
+     * - No filters: Search org-wide
+     *
+     * Additional filtering:
+     *
+     * - status: Filter by workflow status (supports multiple:
+     *   ?status=new&status=reviewed) Valid values: new, reviewed, passed, contacted,
+     *   null
+     */
+    search(query: EntitySearchParams, options?: RequestOptions): APIPromise<EntitySearchResponse>;
+}
+/**
+ * Response model for single entity.
+ *
+ * IMPORTANT: Enrichment fields (sheet_name, entity_type, icp_id) are ALWAYS
+ * populated to support UI annotations. Excludes embedding data for HTTP
+ * efficiency.
+ */
+export interface EntityResponse {
+    /**
+     * Entity ID
+     */
+    id: string;
+    /**
+     * Creation timestamp
+     */
+    created_at: string;
+    /**
+     * Entity attribute data
+     */
+    data: {
+        [key: string]: unknown;
+    };
+    /**
+     * Entity type (company, person, etc.)
+     */
+    entity_type: string;
+    /**
+     * ICP ID (via sheet)
+     */
+    icp_id: string;
+    /**
+     * Sheet this entity belongs to
+     */
+    sheet_id: string;
+    /**
+     * Name of parent sheet
+     */
+    sheet_name: string;
+    /**
+     * Last update timestamp
+     */
+    updated_at: string;
+    /**
+     * User comments
+     */
+    comments?: string | null;
+    /**
+     * Parent entity ID (for hierarchical entities)
+     */
+    parent_id?: string | null;
+    /**
+     * Entity workflow status: new, reviewed, passed, contacted, or null
+     */
+    status?: string | null;
+}
+/**
+ * Paginated list response for entities.
+ *
+ * All entities include enrichment fields (sheet_name, entity_type, icp_id) to
+ * support UI annotations without additional API calls.
+ */
+export interface EntityListResponse {
+    entities: Array<EntityResponse>;
+    /**
+     * Current page (1-based)
+     */
+    page: number;
+    /**
+     * Items per page
+     */
+    page_size: number;
+    /**
+     * Total matching entities (before pagination)
+     */
+    total: number;
+}
+/**
+ * Response for bulk status update operation.
+ *
+ * WHY: Reports both success count and specific failures so the client knows
+ * exactly which entities were updated and which failed.
+ */
+export interface EntityBulkUpdateStatusResponse {
+    /**
+     * Number of entities successfully updated
+     */
+    updated_count: number;
+    /**
+     * Entity IDs that failed to update (invalid format or not found)
+     */
+    failed_ids?: Array<string>;
+}
+export type EntityExportResponse = unknown;
+/**
+ * Response model for entity counts by type.
+ *
+ * Returns counts grouped by entity_type with an aggregate total. Used by Entity
+ * Master List for tab navigation counts.
+ */
+export interface EntityGetCountsResponse {
+    /**
+     * Sum of all entity counts
+     */
+    total: number;
+    /**
+     * Entity counts keyed by entity_type (company, person, etc.)
+     */
+    counts?: {
+        [key: string]: number;
+    };
+}
+/**
+ * Search response with pagination.
+ *
+ * All entities include enrichment fields for UI annotations.
+ */
+export interface EntitySearchResponse {
+    entities: Array<EntityResponse>;
+    /**
+     * Current page (1-based)
+     */
+    page: number;
+    /**
+     * Items per page
+     */
+    page_size: number;
+    /**
+     * Original search query
+     */
+    query: string;
+    /**
+     * Total matching entities
+     */
+    total: number;
+}
+export interface EntityUpdateParams {
+    /**
+     * Update comments (null to clear)
+     */
+    comments?: string | null;
+    /**
+     * Update workflow status: new, reviewed, passed, contacted, or null. Use explicit
+     * null to clear status.
+     */
+    status?: string | null;
+}
+export interface EntityListParams {
+    /**
+     * Valid entity types for sheets.
+     */
+    entity_type?: SheetAPI.EntityType | null;
+    /**
+     * Filter by ICP ID
+     */
+    icp_id?: string | null;
+    /**
+     * Page number (1-based)
+     */
+    page?: number;
+    /**
+     * Items per page
+     */
+    page_size?: number;
+    /**
+     * Filter by sheet ID
+     */
+    sheet_id?: string | null;
+    /**
+     * Filter by status values (supports multiple: ?status=new&status=reviewed)
+     */
+    status?: Array<string> | null;
+}
+export interface EntityBulkUpdateStatusParams {
+    /**
+     * List of entity IDs to update (1-1000 IDs)
+     */
+    entity_ids: Array<string>;
+    /**
+     * New status value: new, reviewed, passed, contacted, or null to clear
+     */
+    status: string | null;
+}
+export interface EntityExportParams {
+    /**
+     * Specific entity IDs
+     */
+    entity_ids?: Array<string> | null;
+    /**
+     * Valid entity types for sheets.
+     */
+    entity_type?: SheetAPI.EntityType | null;
+    /**
+     * Export format: 'separate' (default) or 'combined' (joined parent-child rows)
+     */
+    format?: 'separate' | 'combined';
+    /**
+     * Filter by ICP ID
+     */
+    icp_id?: string | null;
+    /**
+     * Filter by sheet ID
+     */
+    sheet_id?: string | null;
+    /**
+     * Filter by status values (supports multiple: ?status=new&status=contacted)
+     */
+    status?: Array<string> | null;
+}
+export interface EntityGetCountsParams {
+    /**
+     * Filter by ICP ID
+     */
+    icp_id?: string | null;
+    /**
+     * Filter by status values (supports multiple: ?status=new&status=passed)
+     */
+    status?: Array<string> | null;
+}
+export interface EntitySearchParams {
+    /**
+     * Search query
+     */
+    q: string;
+    /**
+     * Valid entity types for sheets.
+     */
+    entity_type?: SheetAPI.EntityType | null;
+    /**
+     * Filter by ICP ID
+     */
+    icp_id?: string | null;
+    /**
+     * Page number
+     */
+    page?: number;
+    /**
+     * Items per page
+     */
+    page_size?: number;
+    /**
+     * Filter by sheet ID
+     */
+    sheet_id?: string | null;
+    /**
+     * Filter by status values (supports multiple: ?status=new&status=reviewed)
+     */
+    status?: Array<string> | null;
+}
+export declare namespace Entity {
+    export { type EntityResponse as EntityResponse, type EntityListResponse as EntityListResponse, type EntityBulkUpdateStatusResponse as EntityBulkUpdateStatusResponse, type EntityExportResponse as EntityExportResponse, type EntityGetCountsResponse as EntityGetCountsResponse, type EntitySearchResponse as EntitySearchResponse, type EntityUpdateParams as EntityUpdateParams, type EntityListParams as EntityListParams, type EntityBulkUpdateStatusParams as EntityBulkUpdateStatusParams, type EntityExportParams as EntityExportParams, type EntityGetCountsParams as EntityGetCountsParams, type EntitySearchParams as EntitySearchParams, };
+}
+//# sourceMappingURL=entity.d.mts.map

package/resources/entity.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.mts","sourceRoot":"","sources":["../src/resources/entity.ts"],"names":[],"mappings":"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"}