@linkt/sdk 0.2.0

package/src/internal/utils/values.ts

@@ -0,0 +1,105 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { LinktError } from '../../core/error';
+
+// https://url.spec.whatwg.org/#url-scheme-string
+const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
+
+export const isAbsoluteURL = (url: string): boolean => {
+  return startsWithSchemeRegexp.test(url);
+};
+
+export let isArray = (val: unknown): val is unknown[] => ((isArray = Array.isArray), isArray(val));
+export let isReadonlyArray = isArray as (val: unknown) => val is readonly unknown[];
+
+/** Returns an object if the given value isn't an object, otherwise returns as-is */
+export function maybeObj(x: unknown): object {
+  if (typeof x !== 'object') {
+    return {};
+  }
+
+  return x ?? {};
+}
+
+// https://stackoverflow.com/a/34491287
+export function isEmptyObj(obj: Object | null | undefined): boolean {
+  if (!obj) return true;
+  for (const _k in obj) return false;
+  return true;
+}
+
+// https://eslint.org/docs/latest/rules/no-prototype-builtins
+export function hasOwn<T extends object = object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+export const ensurePresent = <T>(value: T | null | undefined): T => {
+  if (value == null) {
+    throw new LinktError(`Expected a value to be given but received ${value} instead.`);
+  }
+
+  return value;
+};
+
+export const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
+    throw new LinktError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new LinktError(`${name} must be a positive integer`);
+  }
+  return n;
+};
+
+export const coerceInteger = (value: unknown): number => {
+  if (typeof value === 'number') return Math.round(value);
+  if (typeof value === 'string') return parseInt(value, 10);
+
+  throw new LinktError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceFloat = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return parseFloat(value);
+
+  throw new LinktError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceBoolean = (value: unknown): boolean => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value === 'true';
+  return Boolean(value);
+};
+
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
+export const safeJSON = (text: string) => {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+};

package/src/internal/utils.ts

@@ -0,0 +1,8 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './utils/values';
+export * from './utils/base64';
+export * from './utils/env';
+export * from './utils/log';
+export * from './utils/uuid';
+export * from './utils/sleep';

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/resource.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/resource instead */
+export * from './core/resource';

package/src/resources/files.ts

@@ -0,0 +1,219 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { type Uploadable } from '../core/uploads';
+import { RequestOptions } from '../internal/request-options';
+import { multipartFormRequestOptions } from '../internal/uploads';
+import { path } from '../internal/utils/path';
+
+export class Files extends APIResource {
+  /**
+   * Get file details by ID.
+   *
+   * Returns metadata for a specific file including name, size, and processing
+   * status. Use this to check if a file is ready for use in workflows.
+   */
+  retrieve(fileID: string, options?: RequestOptions): APIPromise<FileRetrieveResponse> {
+    return this._client.get(path`/v1/files/${fileID}`, options);
+  }
+
+  /**
+   * List uploaded files.
+   *
+   * Returns a paginated list of all files uploaded by your organization. Files can
+   * be used as data sources for signal monitoring and ingest tasks.
+   */
+  list(
+    query: FileListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<FileListResponse> {
+    return this._client.get('/v1/files', { query, ...options });
+  }
+
+  /**
+   * Upload a CSV or XLSX file.
+   *
+   * Upload a data file for use in signal monitoring or ingest workflows. The file is
+   * stored securely and can be referenced when creating tasks. XLSX files are
+   * automatically converted to CSV format (first sheet only).
+   */
+  upload(body: FileUploadParams, options?: RequestOptions): APIPromise<FileUploadResponse> {
+    return this._client.post(
+      '/v1/files/upload',
+      multipartFormRequestOptions({ body, ...options }, this._client),
+    );
+  }
+}
+
+/**
+ * Processing status for CSV files.
+ */
+export type CsvProcessingStatus = 'pending' | 'processing' | 'completed' | 'failed';
+
+/**
+ * Response model for file details.
+ */
+export interface FileRetrieveResponse {
+  /**
+   * Content type of the file
+   */
+  content_type: string;
+
+  /**
+   * The ID of the file
+   */
+  file_id: string;
+
+  /**
+   * The name of the file
+   */
+  name: string;
+
+  /**
+   * S3 URI of the file
+   */
+  s3_uri: string;
+
+  /**
+   * Size of the file in bytes
+   */
+  size_bytes: number;
+
+  /**
+   * CSV metadata
+   */
+  csv_metadata?: { [key: string]: unknown };
+
+  /**
+   * Original file type if converted (e.g., 'xlsx' if XLSX was converted to CSV)
+   */
+  original_file_type?: string | null;
+
+  /**
+   * Processing status
+   */
+  processing_status?: CsvProcessingStatus;
+}
+
+/**
+ * Response model for file listing.
+ */
+export interface FileListResponse {
+  /**
+   * List of files
+   */
+  files: Array<FileListResponse.File>;
+
+  /**
+   * Current page number
+   */
+  page: number;
+
+  /**
+   * Number of items per page
+   */
+  page_size: number;
+
+  /**
+   * Total number of files
+   */
+  total: number;
+}
+
+export namespace FileListResponse {
+  /**
+   * File item in list response.
+   */
+  export interface File {
+    /**
+     * The ID of the file
+     */
+    file_id: string;
+
+    /**
+     * The name of the file
+     */
+    name: string;
+
+    /**
+     * Size of the file in bytes
+     */
+    size_bytes: number;
+  }
+}
+
+/**
+ * Response model for file upload.
+ */
+export interface FileUploadResponse {
+  /**
+   * Content type of the file
+   */
+  content_type: string;
+
+  /**
+   * The ID of the uploaded file
+   */
+  file_id: string;
+
+  /**
+   * The name of the file
+   */
+  name: string;
+
+  /**
+   * Processing status
+   */
+  processing_status: CsvProcessingStatus;
+
+  /**
+   * S3 URI of the uploaded file
+   */
+  s3_uri: string;
+
+  /**
+   * Size of the file in bytes
+   */
+  size_bytes: number;
+
+  /**
+   * CSV metadata
+   */
+  csv_metadata?: { [key: string]: unknown };
+
+  /**
+   * Original file type if converted (e.g., 'xlsx' if XLSX was converted to CSV)
+   */
+  original_file_type?: string | null;
+}
+
+export interface FileListParams {
+  /**
+   * Page number (1-based)
+   */
+  page?: number;
+
+  /**
+   * Items per page
+   */
+  page_size?: number;
+}
+
+export interface FileUploadParams {
+  /**
+   * CSV or XLSX file to upload
+   */
+  file: Uploadable;
+}
+
+export declare namespace Files {
+  export {
+    type CsvProcessingStatus as CsvProcessingStatus,
+    type FileRetrieveResponse as FileRetrieveResponse,
+    type FileListResponse as FileListResponse,
+    type FileUploadResponse as FileUploadResponse,
+    type FileListParams as FileListParams,
+    type FileUploadParams as FileUploadParams,
+  };
+}

package/src/resources/icp.ts

@@ -0,0 +1,227 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Icp extends APIResource {
+  /**
+   * Create a new Ideal Customer Profile (ICP).
+   *
+   * ICPs are the foundation of your research workflows. They define WHAT entities to
+   * target using business-level descriptions and filters, without specifying
+   * technical implementation details.
+   *
+   * Create an ICP first, then link Sheets to it for entity storage.
+   */
+  create(body: IcpCreateParams, options?: RequestOptions): APIPromise<IcpResponse> {
+    return this._client.post('/v1/icp', { body, ...options });
+  }
+
+  /**
+   * Get a specific ICP by ID.
+   */
+  retrieve(icpID: string, options?: RequestOptions): APIPromise<IcpResponse> {
+    return this._client.get(path`/v1/icp/${icpID}`, options);
+  }
+
+  /**
+   * Update an existing ICP.
+   *
+   * Only provided fields will be updated; omitted fields remain unchanged.
+   */
+  update(icpID: string, body: IcpUpdateParams, options?: RequestOptions): APIPromise<IcpResponse> {
+    return this._client.put(path`/v1/icp/${icpID}`, { body, ...options });
+  }
+
+  /**
+   * List all ICPs for the organization.
+   *
+   * Results are scoped to your organization. Use the `mode` filter to separate
+   * discovery ICPs (for finding new entities) from monitoring ICPs (for tracking
+   * existing entities).
+   */
+  list(query: IcpListParams | null | undefined = {}, options?: RequestOptions): APIPromise<IcpListResponse> {
+    return this._client.get('/v1/icp', { query, ...options });
+  }
+
+  /**
+   * Delete an ICP and all related resources.
+   *
+   * **Cascade delete**: This permanently removes the ICP along with all associated
+   * sheets, entities, schedules, tasks, and signals. This operation cannot be
+   * undone.
+   */
+  delete(icpID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/icp/${icpID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Get all active runs for an ICP.
+   *
+   * Returns runs in non-terminal states (RUNNING, SCHEDULED, PENDING). Useful for
+   * checking if workflows are currently processing this ICP before making changes.
+   */
+  getActiveRuns(icpID: string, options?: RequestOptions): APIPromise<IcpGetActiveRunsResponse> {
+    return this._client.get(path`/v1/icp/${icpID}/active_runs`, options);
+  }
+}
+
+/**
+ * Request model for entity target configuration.
+ */
+export interface EntityTargetConfig {
+  /**
+   * Business description of targets
+   */
+  description: string;
+
+  /**
+   * Entity type to target
+   */
+  entity_type: string;
+
+  /**
+   * Filters to apply
+   */
+  filters?: Array<string>;
+}
+
+/**
+ * Response model for ICP.
+ */
+export interface IcpResponse {
+  id: string;
+
+  created_at: string;
+
+  description: string;
+
+  entity_targets: Array<IcpResponse.EntityTarget>;
+
+  name: string;
+
+  updated_at: string;
+}
+
+export namespace IcpResponse {
+  /**
+   * Response model for entity target configuration.
+   */
+  export interface EntityTarget {
+    description: string;
+
+    entity_type: string;
+
+    root: boolean;
+  }
+}
+
+/**
+ * Response for listing ICPs.
+ */
+export interface IcpListResponse {
+  icps: Array<IcpResponse>;
+
+  page: number;
+
+  page_size: number;
+
+  total: number;
+}
+
+/**
+ * Response model for ICP running status.
+ */
+export interface IcpGetActiveRunsResponse {
+  runs: Array<IcpGetActiveRunsResponse.Run>;
+}
+
+export namespace IcpGetActiveRunsResponse {
+  /**
+   * Individual run status item for API responses.
+   *
+   * Includes both agent_type (execution context) and task_type (workflow type)
+   * fields to support filtering and display during the transition from legacy runs.
+   *
+   * Attributes: id: Unique run identifier (ObjectId as string) agent_type: HOW the
+   * run was triggered ("task", "play") task_type: WHAT workflow runs ("signal",
+   * "search", "profile", "ingest"). None for plays or legacy runs without this
+   * field. created_at: When the run was created
+   */
+  export interface Run {
+    /**
+     * Run ID
+     */
+    id: string;
+
+    /**
+     * Execution context (task, play)
+     */
+    agent_type: string;
+
+    /**
+     * Creation timestamp
+     */
+    created_at?: string | null;
+
+    /**
+     * Workflow type for task-based runs (signal, search, profile, ingest)
+     */
+    task_type?: string | null;
+  }
+}
+
+export interface IcpCreateParams {
+  description: string;
+
+  entity_targets: Array<EntityTargetConfig>;
+
+  name: string;
+}
+
+export interface IcpUpdateParams {
+  description?: string | null;
+
+  entity_targets?: Array<EntityTargetConfig> | null;
+
+  name?: string | null;
+}
+
+export interface IcpListParams {
+  /**
+   * Filter by ICP mode: 'discovery' or 'monitoring'
+   */
+  mode?: 'discovery' | 'monitoring' | null;
+
+  /**
+   * Sort order: -1 for descending, 1 for ascending
+   */
+  order?: number | null;
+
+  page?: number;
+
+  page_size?: number;
+
+  /**
+   * Field to sort by (e.g., 'created_at', 'updated_at', 'name')
+   */
+  sort_by?: string | null;
+}
+
+export declare namespace Icp {
+  export {
+    type EntityTargetConfig as EntityTargetConfig,
+    type IcpResponse as IcpResponse,
+    type IcpListResponse as IcpListResponse,
+    type IcpGetActiveRunsResponse as IcpGetActiveRunsResponse,
+    type IcpCreateParams as IcpCreateParams,
+    type IcpUpdateParams as IcpUpdateParams,
+    type IcpListParams as IcpListParams,
+  };
+}

package/src/resources/index.ts

@@ -0,0 +1,64 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Files,
+  type CsvProcessingStatus,
+  type FileRetrieveResponse,
+  type FileListResponse,
+  type FileUploadResponse,
+  type FileListParams,
+  type FileUploadParams,
+} from './files';
+export {
+  Icp,
+  type EntityTargetConfig,
+  type IcpResponse,
+  type IcpListResponse,
+  type IcpGetActiveRunsResponse,
+  type IcpCreateParams,
+  type IcpUpdateParams,
+  type IcpListParams,
+} from './icp';
+export {
+  Run,
+  type RunCreateResponse,
+  type RunRetrieveResponse,
+  type RunListResponse,
+  type RunGetQueueResponse,
+  type RunCreateParams,
+  type RunListParams,
+  type RunGetQueueParams,
+} from './run';
+export {
+  SheetResource,
+  type EntityType,
+  type Sheet,
+  type SheetListResponse,
+  type SheetExportCsvResponse,
+  type SheetGetEntitiesResponse,
+  type SheetCreateParams,
+  type SheetUpdateParams,
+  type SheetListParams,
+  type SheetExportCsvParams,
+  type SheetGetEntitiesParams,
+} from './sheet/sheet';
+export { Signal, type SignalResponse, type SignalListResponse, type SignalListParams } from './signal';
+export {
+  Task,
+  type IngestTaskConfig,
+  type SearchV2Config,
+  type SearchV3Config,
+  type SignalCsvConfigInput,
+  type SignalSheetConfigInput,
+  type SignalTopicConfigInput,
+  type SignalTypeConfig,
+  type StandardPromptConfig,
+  type TaskCreateResponse,
+  type TaskRetrieveResponse,
+  type TaskListResponse,
+  type TaskExecuteResponse,
+  type TaskCreateParams,
+  type TaskUpdateParams,
+  type TaskListParams,
+  type TaskExecuteParams,
+} from './task';