@graph8/sdk 0.251.0 → 0.262.0

package/dist/types/search.d.ts

@@ -0,0 +1,99 @@
+/** Filter operators supported by open-data search. */
+export type SearchOperator = "any_of" | "contains" | "all_of" | "none_of" | "is_empty" | "is_not_empty" | "between" | "exists";
+/** A single search filter condition (named to avoid colliding with enrich's `SearchFilter`). */
+export interface SearchCondition {
+    /** Field to filter on, e.g. "job_title", "country", "industry". */
+    field: string;
+    operator: SearchOperator;
+    /** Filter values (operator-dependent; e.g. `["VP", "Director"]` for any_of). */
+    value?: unknown[];
+}
+export interface SearchParams {
+    /** Filter conditions, combined with AND. */
+    filters?: SearchCondition[];
+    /** Page number, 1-indexed (1-100). */
+    page?: number;
+    /** Results per page (1-100, default 25). */
+    limit?: number;
+}
+export interface SearchSaveParams extends SearchParams {
+    /** Title for the new list the matched records are saved into. */
+    list_title: string;
+    /** Max records to save (1-10,000, default 1,000). */
+    max_results?: number;
+}
+export interface SearchContactItem {
+    first_name?: string | null;
+    last_name?: string | null;
+    middle_name?: string | null;
+    work_email?: string | null;
+    personal_emails?: string | null;
+    direct_phone?: string | null;
+    mobile_phone?: string | null;
+    job_title?: string | null;
+    job_department?: string | null;
+    seniority_level?: string | null;
+    role?: string | null;
+    linkedin_url?: string | null;
+    linkedin_headline?: string | null;
+    city?: string | null;
+    state?: string | null;
+    country?: string | null;
+    company_name?: string | null;
+    company_domain?: string | null;
+    company_industry?: string | null;
+    company_employee_count?: string | null;
+    company_country?: string | null;
+    confidence_score?: number | null;
+}
+export interface SearchCompanyItem {
+    name?: string | null;
+    domain?: string | null;
+    website?: string | null;
+    description?: string | null;
+    industry?: string | null;
+    industry_group?: string | null;
+    employee_count?: string | null;
+    revenue?: string | null;
+    founded_year?: number | null;
+    phone?: string | null;
+    address?: string | null;
+    city?: string | null;
+    state?: string | null;
+    country?: string | null;
+    zip?: number | null;
+    linkedin_url?: string | null;
+    linkedin_followers?: string | null;
+    facebook_url?: string | null;
+    twitter_url?: string | null;
+    crunchbase_url?: string | null;
+    logo_url?: string | null;
+}
+export interface SearchSaveResult {
+    list_id: number;
+    list_title: string;
+    estimated_total: number;
+    status: string;
+}
+/**
+ * Search API — prospect the open-data graph for new contacts and companies by
+ * filter, and optionally save the matches straight into a list. Requires API
+ * key (server-side). Built on the hardened HTTP core, so every method throws a
+ * typed `G8Error` on failure and retries transient errors.
+ *
+ * Backed by `/api/v1/search`.
+ */
+export declare const createSearchClient: (apiKey: string, apiUrl?: string) => {
+    /** Search open-data contacts by filter. */
+    contacts(params?: SearchParams): Promise<{
+        data: SearchContactItem[];
+    }>;
+    /** Search open-data companies by filter. */
+    companies(params?: SearchParams): Promise<{
+        data: SearchCompanyItem[];
+    }>;
+    /** Search contacts and save the matches into a new list. */
+    saveContacts(params: SearchSaveParams): Promise<SearchSaveResult>;
+    /** Search companies and save the matches into a new list. */
+    saveCompanies(params: SearchSaveParams): Promise<SearchSaveResult>;
+};

package/dist/types/sequences.d.ts

@@ -0,0 +1,255 @@
+export interface Sequence {
+    id: string;
+    name: string;
+    status: string;
+    step_count: number | null;
+    contact_count: number | null;
+}
+export interface AddToSequenceConfig {
+    sequenceId: string;
+    contactIds: number[];
+    listId: number;
+}
+export interface SequenceListItem {
+    id: string;
+    name: string | null;
+    status: string | null;
+    user_email: string | null;
+    step_count: number | null;
+    contact_count: number | null;
+    sequence_kind: string | null;
+    associated_list_id: number | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface SequenceListParams {
+    page?: number;
+    limit?: number;
+    /** Filter by sequence status (e.g. "live", "draft", "paused"). */
+    status?: string;
+    /** Filter by sequence kind ("cold_outbound" or "nurture"). Omit to list all kinds. */
+    sequence_kind?: SequenceKind;
+}
+export interface SequenceDetail {
+    id: string;
+    name: string | null;
+    description: string | null;
+    status: string | null;
+    user_email: string | null;
+    associated_list_id: number | null;
+    finish_on_reply: boolean;
+    send_in_same_thread: boolean;
+    wait_for_new_contacts: boolean;
+    paused_at: string | null;
+    resumed_at: string | null;
+    /** Sequence kind. Immutable after creation. "cold_outbound" (default) or "nurture". */
+    sequence_kind?: string | null;
+    /** Pinned mailbox for nurture sequences; null for cold_outbound. Immutable. */
+    pinned_mailbox_id?: number | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface SequenceContactItem {
+    id: string | null;
+    contact_id: number | null;
+    state: string | null;
+    current_step_order: number | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface SequenceContactsParams {
+    page?: number;
+    limit?: number;
+    /** Filter by contact state (e.g. "active", "completed", "replied"). */
+    state?: string;
+}
+export interface SequenceActionResult {
+    sequence_id: string;
+    status: string;
+    contacts_affected: number;
+}
+/**
+ * Step type. Note: LinkedIn flows use "HEYREACH" — there is no "LINKEDIN" step type.
+ * Server is case-insensitive on input but stores uppercase.
+ */
+export type SequenceStepType = "EMAIL" | "PHONE" | "SMS" | "WHATSAPP" | "HEYREACH" | "MANUAL_DIALER";
+export type SequenceStepInputType = "ON_DEMAND" | "MANUAL_TEMPLATE" | "AI_GENERATED_TEMPLATE";
+export interface SequenceStepConfig {
+    step_order: number;
+    step_type: SequenceStepType | string;
+    /** Defaults to "ON_DEMAND". */
+    input_type?: SequenceStepInputType | string;
+    /** Wait time before this step in seconds. Defaults to 0. */
+    time_interval?: number;
+    /** Template body, AI prompt, or other step-type-specific config. */
+    step_data?: Record<string, unknown>;
+}
+export interface SequenceChannelConfig {
+    channel_id: number;
+    channel_value: string;
+    channel_type: string;
+    channel_data?: Record<string, unknown>;
+}
+/**
+ * Sequence kind. A "nurture" is an ordinary sequence with `sequence_kind:
+ * "nurture"` — same step types as cold outreach, but pinned to a single mailbox
+ * with a higher daily email cap. There is no separate nurture client; create one
+ * via `sequences.create({ sequence_kind: "nurture", pinned_mailbox_id })`.
+ */
+export type SequenceKind = "cold_outbound" | "nurture";
+export interface SequenceCreateParams {
+    name: string;
+    user_email: string;
+    description?: string;
+    finish_on_reply?: boolean;
+    send_in_same_thread?: boolean;
+    wait_for_new_contacts?: boolean;
+    associated_list_id?: number;
+    steps?: SequenceStepConfig[];
+    channels?: SequenceChannelConfig[];
+    campaign_id?: string;
+    /**
+     * Sequence kind. Defaults to "cold_outbound" server-side. Immutable after
+     * creation. "nurture" requires `pinned_mailbox_id` and is gated by the
+     * ENABLE_NURTURE feature flag.
+     */
+    sequence_kind?: SequenceKind;
+    /**
+     * Mailbox to pin for a nurture sequence. Required when
+     * `sequence_kind: "nurture"`; all email channels must use this mailbox.
+     * Ignored for cold_outbound sequences.
+     */
+    pinned_mailbox_id?: number;
+}
+export interface SequenceCreateResult {
+    id: string;
+    name: string;
+    status: string;
+    created_at: string | null;
+}
+export interface SequenceUpdateParams {
+    name?: string;
+    description?: string;
+    is_shared?: boolean;
+    finish_on_reply?: boolean;
+    send_in_same_thread?: boolean;
+    wait_for_new_contacts?: boolean;
+    schedule_id?: string;
+    appointment_id?: number;
+}
+export interface SequenceStepUpdateParams {
+    step_data?: Record<string, unknown>;
+    time_interval?: number;
+    step_type?: SequenceStepType | string;
+    input_type?: SequenceStepInputType | string;
+}
+export interface SequencePreviewStep {
+    id: string;
+    step_order: number;
+    step_type: string;
+    input_type: string;
+    time_interval: number | null;
+    step_data: Record<string, unknown> | null;
+}
+export interface SequencePreviewChannel {
+    id: string;
+    channel_id: number | null;
+    channel_value: string | null;
+    channel_type: string | null;
+}
+export interface SequencePreview {
+    id: string;
+    name: string | null;
+    status: string | null;
+    description: string | null;
+    steps: SequencePreviewStep[];
+    channels: SequencePreviewChannel[];
+}
+export interface SequenceAnalytics {
+    overview: Record<string, unknown>;
+    performance: Record<string, unknown>;
+    engagement: Record<string, unknown>;
+    timeline: Record<string, unknown>[];
+    contact_distribution: Record<string, unknown>;
+    step_breakdown: Record<string, unknown>[];
+    step_creation_methods: Record<string, unknown>[];
+    sender_distribution: Record<string, unknown>[];
+}
+export interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    has_next: boolean;
+}
+/**
+ * Sequences API — list, create, run, pause, update, analyze multi-channel sequences.
+ * Requires API key (server-side).
+ *
+ * Backed by:
+ *   GET    /api/v1/sequences
+ *   POST   /api/v1/sequences
+ *   GET    /api/v1/sequences/{sequence_id}
+ *   PATCH  /api/v1/sequences/{sequence_id}
+ *   DELETE /api/v1/sequences/{sequence_id}
+ *   GET    /api/v1/sequences/{sequence_id}/contacts
+ *   POST   /api/v1/sequences/{sequence_id}/contacts
+ *   POST   /api/v1/sequences/{sequence_id}/run
+ *   POST   /api/v1/sequences/{sequence_id}/pause
+ *   POST   /api/v1/sequences/{sequence_id}/resume
+ *   PATCH  /api/v1/sequences/{sequence_id}/steps/{step_id}
+ *   GET    /api/v1/sequences/{sequence_id}/preview
+ *   GET    /api/v1/sequences/{sequence_id}/analytics
+ */
+export declare const createSequencesClient: (apiKey: string, apiUrl?: string) => {
+    /** List sequences with pagination + optional status filter. */
+    list: {
+        (): Promise<SequenceListItem[]>;
+        (page: number, limit?: number): Promise<SequenceListItem[]>;
+        (params: SequenceListParams): Promise<SequenceListItem[]>;
+    };
+    /** Get full sequence details by ID. */
+    get(sequenceId: string): Promise<SequenceDetail>;
+    /** List contacts enrolled in a sequence. Filter by state (e.g. "active", "replied"). */
+    contacts(sequenceId: string, params?: SequenceContactsParams): Promise<{
+        data: SequenceContactItem[];
+        pagination?: PaginationMeta;
+    }>;
+    /**
+     * Add contacts to a sequence (V2 queuing). Live or drafted sequences only.
+     * Pass `idempotencyKey` to make a retry safe — the same key returns the
+     * first result instead of re-enrolling on a 5xx-then-success (A6).
+     */
+    add(config: AddToSequenceConfig, idempotencyKey?: string): Promise<SequenceActionResult>;
+    /**
+     * Create a new sequence with optional steps + channels. Pass `idempotencyKey`
+     * to make a retry safe — the same key returns the first result instead of
+     * creating a duplicate sequence on a 5xx-then-success (A6).
+     */
+    create(payload: SequenceCreateParams, idempotencyKey?: string): Promise<SequenceCreateResult>;
+    /** Update sequence metadata. Rejected (409) if sequence is in a transitional status. */
+    update(sequenceId: string, fields: SequenceUpdateParams): Promise<SequenceActionResult>;
+    /** Update a single step within a sequence. */
+    updateStep(sequenceId: string, stepId: string, fields: SequenceStepUpdateParams): Promise<SequenceActionResult>;
+    /** Soft-delete (archive) a sequence. */
+    delete(sequenceId: string): Promise<SequenceActionResult>;
+    /**
+     * Run/start a DRAFTED sequence (V2 orchestration). Pass `idempotencyKey` to
+     * make a retry safe — the same key won't re-trigger the run on a
+     * 5xx-then-success (A6).
+     */
+    run(sequenceId: string, idempotencyKey?: string): Promise<SequenceActionResult>;
+    /**
+     * Pause a live sequence. Pass `idempotencyKey` to make a retry safe — the
+     * same key won't double-apply on a 5xx-then-success (A6).
+     */
+    pause(sequenceId: string, idempotencyKey?: string): Promise<SequenceActionResult>;
+    /**
+     * Resume a paused sequence. Pass `idempotencyKey` to make a retry safe — the
+     * same key won't double-apply on a 5xx-then-success (A6).
+     */
+    resume(sequenceId: string, idempotencyKey?: string): Promise<SequenceActionResult>;
+    /** Read-only sequence preview with all steps + channels (no enrollment). */
+    preview(sequenceId: string): Promise<SequencePreview>;
+    /** Comprehensive analytics for a sequence. */
+    analytics(sequenceId: string): Promise<SequenceAnalytics>;
+};

package/dist/types/signals.d.ts

@@ -0,0 +1,28 @@
+export interface IntentSignals {
+    domain: string;
+    score: number;
+    intent: "low" | "medium" | "high";
+    signals: string[];
+    last_seen: string | null;
+}
+/**
+ * Intent signals - company-level buying signals. Write key for public, API key for full access.
+ */
+export declare const createSignalsClient: (key: string, isApiKey: boolean, apiUrl?: string) => {
+    /**
+     * Get intent signals for a specific company domain.
+     *
+     * With an API key this throws a `G8Error` on any failure; a 403 means the
+     * key lacks the `intent:read` scope. With a write key only, a failure still
+     * resolves to an all-zeros result (legacy browser behaviour).
+     */
+    company(domain: string): Promise<IntentSignals>;
+    /**
+     * Stream intent signals - calls callback every 30s with latest data.
+     *
+     * A failed poll is skipped. An auth failure (401/403) cannot fix itself by
+     * waiting, so it stops the stream and is logged once instead of polling a
+     * forbidden route every 30s forever.
+     */
+    stream(domains: string[], callback: (signals: IntentSignals[]) => void): () => void;
+};

package/dist/types/skills.d.ts

@@ -0,0 +1,176 @@
+export type SkillType = "llm" | "api";
+export interface SkillInputField {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+}
+export interface Skill {
+    id: string;
+    title: string;
+    description: string | null;
+    type: SkillType;
+    /** Only present on `type=llm`. */
+    prompt?: string;
+    /** Only present on `type=llm`. */
+    model?: string;
+    /** Only present on `type=api`. */
+    method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+    /** Only present on `type=api`. */
+    url?: string;
+    /** Only present on `type=api`. */
+    headers?: Record<string, string>;
+    /** Only present on `type=api`. */
+    body_template?: string;
+    input_schema: {
+        fields: SkillInputField[];
+    };
+    output_schema: Record<string, unknown> | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface SkillCreateLLMParams {
+    title: string;
+    description?: string;
+    prompt: string;
+    model: string;
+    input_schema: {
+        fields: SkillInputField[];
+    };
+    output_schema?: Record<string, unknown>;
+}
+export interface SkillCreateAPIParams {
+    title: string;
+    description?: string;
+    method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+    url: string;
+    headers?: Record<string, string>;
+    body_template?: string;
+    response_mapping?: Record<string, string>;
+    input_schema: {
+        fields: SkillInputField[];
+    };
+}
+export interface SkillUpdateLLMParams {
+    title?: string;
+    description?: string;
+    prompt?: string;
+    model?: string;
+    input_schema?: {
+        fields: SkillInputField[];
+    };
+    output_schema?: Record<string, unknown>;
+}
+export interface SkillUpdateAPIParams {
+    title?: string;
+    description?: string;
+    method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+    url?: string;
+    headers?: Record<string, string>;
+    body_template?: string;
+    response_mapping?: Record<string, string>;
+    input_schema?: {
+        fields: SkillInputField[];
+    };
+}
+export interface SkillTemplate {
+    id: string;
+    title: string;
+    description: string;
+    type: SkillType;
+    use_cases: string[];
+}
+export interface SkillListParams {
+    page?: number;
+    limit?: number;
+    type?: SkillType;
+    search?: string;
+}
+/**
+ * Skills API - LLM and API building blocks that workflows compose into runs.
+ * Requires API key (server-side).
+ *
+ * Backed by:
+ *   GET    /api/v1/skills
+ *   GET    /api/v1/skills/{id}
+ *   GET    /api/v1/skills/{id}/variables
+ *   GET    /api/v1/skills/models
+ *   GET    /api/v1/skills/templates
+ *   POST   /api/v1/skills              (both llm + api types via `type` field)
+ *   POST   /api/v1/skills/from-template
+ *   POST   /api/v1/skills/from-node
+ *   PUT    /api/v1/skills/{id}
+ *   DELETE /api/v1/skills/{id}
+ *   POST   /api/v1/skills/validate
+ *   POST   /api/v1/skills/{id}/execute
+ */
+export declare const createSkillsClient: (apiKey: string, apiUrl?: string) => {
+    /** List skills. */
+    list(params?: SkillListParams): Promise<{
+        data: Skill[];
+    }>;
+    /** Get a skill by ID. */
+    get(skillId: string): Promise<Skill>;
+    /** Get the variables required by a skill (extracted from prompt or body template). */
+    getVariables(skillId: string): Promise<{
+        data: SkillInputField[];
+    }>;
+    /** List available LLM models. */
+    listModels(): Promise<{
+        data: Array<{
+            id: string;
+            label: string;
+            provider: string;
+        }>;
+    }>;
+    /** List skill templates. */
+    listTemplates(params?: {
+        type?: SkillType;
+    }): Promise<{
+        data: SkillTemplate[];
+    }>;
+    /** Create an LLM skill (prompt + model + schemas). */
+    createLLM(params: SkillCreateLLMParams): Promise<Skill>;
+    /** Create an API skill (HTTP request wrapper). */
+    createAPI(params: SkillCreateAPIParams): Promise<Skill>;
+    /** Create a skill from a built-in template. */
+    createFromTemplate(params: {
+        title: string;
+        template_id: string;
+        overrides?: Record<string, unknown>;
+    }): Promise<Skill>;
+    /** Lift a workflow node into a reusable skill. */
+    createFromNode(params: {
+        title: string;
+        description?: string;
+        node_id: string;
+        input_mapping?: Record<string, string>;
+        output_mapping?: Record<string, string>;
+    }): Promise<Skill>;
+    /** Update an LLM skill. */
+    updateLLM(skillId: string, fields: SkillUpdateLLMParams): Promise<Skill>;
+    /** Update an API skill. */
+    updateAPI(skillId: string, fields: SkillUpdateAPIParams): Promise<Skill>;
+    /** Delete a skill (irreversible if in-use workflows exist). */
+    delete(skillId: string): Promise<{
+        data: {
+            deleted: boolean;
+        };
+    }>;
+    /** Validate a skill definition (without saving). */
+    validate(skill: Partial<Skill>): Promise<{
+        data: {
+            valid: boolean;
+            errors: string[];
+        };
+    }>;
+    /** Execute a skill immediately with an input payload (test / preview). */
+    execute(skillId: string, inputPayload: Record<string, unknown>): Promise<{
+        data: {
+            output: Record<string, unknown>;
+            latency_ms: number;
+            tokens?: number;
+            error: string | null;
+        };
+    }>;
+};

package/dist/types/snippet.d.ts

@@ -0,0 +1,24 @@
+export interface Snippet {
+    write_key: string;
+    tracking_host: string;
+    domains: string[];
+    /** Ready-to-use React component import for @graph8/nextjs. */
+    react_snippet: string;
+    /** Vanilla JS script tag for non-React apps. */
+    script_tag: string;
+    /** Full configuration object (gtm/config.json). */
+    config: Record<string, unknown>;
+}
+/**
+ * Snippet API — fetch your org's graph8 tracking snippet programmatically, to
+ * embed the tracker into an app or a customer's site (the write key, a React
+ * component, a vanilla `<script>` tag, allowed domains, and the full config).
+ * Requires an API key (server-side). Built on the hardened HTTP core, so it
+ * throws a typed `G8Error` on failure and retries transient errors.
+ *
+ * Backed by `GET /api/v1/snippet`.
+ */
+export declare const createSnippetClient: (apiKey: string, apiUrl?: string) => {
+    /** Get your org's tracking snippet (write key + React/script-tag embeds + config). */
+    get(): Promise<Snippet>;
+};