@graph8/sdk 0.251.0 → 0.262.0

package/dist/types/studio.d.ts

@@ -0,0 +1,161 @@
+export interface GlobalContextDocument {
+    id: string;
+    category: string;
+    title: string;
+    content: string;
+    metadata: Record<string, unknown> | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface Persona {
+    id: string;
+    name: string;
+    description: string | null;
+    status: string;
+    pain_points: string[];
+    goals: string[];
+    channels: string[];
+    created_at: string | null;
+}
+export interface ICP {
+    id: string;
+    name: string;
+    description: string | null;
+    status: string;
+    industry: string[] | null;
+    employee_count_min: number | null;
+    employee_count_max: number | null;
+    revenue_min: number | null;
+    revenue_max: number | null;
+    countries: string[] | null;
+    created_at: string | null;
+}
+export interface IntelligenceData {
+    id: string;
+    source_type: string;
+    url: string | null;
+    title: string | null;
+    content_summary: string | null;
+    collected_at: string | null;
+}
+export interface ResearchReport {
+    id: string;
+    category: "buyer_psychology" | "competitive_teardown" | "gtm_channel" | "industry_analyst" | "review_sentiment" | "voice_of_customer";
+    title: string;
+    summary: string | null;
+    created_at: string | null;
+}
+/**
+ * Studio context — org-level intelligence documents. The 44-doc engine that
+ * powers campaign ideation: brand brief, value props, messaging house, ICPs,
+ * personas, intelligence (scrapes + enrichment), and AI research reports.
+ *
+ * Requires API key (server-side).
+ *
+ * Backed by:
+ *   GET   /api/v1/global-context/documents
+ *   GET   /api/v1/icps           POST /api/v1/icps           PATCH /api/v1/icps/{id}           POST /api/v1/icps/{id}/archive
+ *   GET   /api/v1/personas       POST /api/v1/personas       PATCH /api/v1/personas/{id}       POST /api/v1/personas/{id}/archive
+ *   GET   /api/v1/intelligence-data
+ *   GET   /api/v1/research-reports
+ */
+export declare const createStudioClient: (apiKey: string, apiUrl?: string) => {
+    /** Org-level Studio documents (brand_brief, value_props, messaging_house, etc.).
+     * `include_content` defaults to true server-side, so each document includes
+     * its `content` body unless you explicitly pass `include_content: false`. */
+    globalContext(params?: {
+        category?: string;
+        limit?: number;
+        include_content?: boolean;
+    }): Promise<{
+        data: GlobalContextDocument[];
+    }>;
+    /** ICP definitions. */
+    icps(params?: {
+        status?: string;
+        limit?: number;
+    }): Promise<{
+        data: ICP[];
+    }>;
+    /** Buyer persona definitions. */
+    personas(params?: {
+        status?: string;
+        limit?: number;
+    }): Promise<{
+        data: Persona[];
+    }>;
+    /** Intelligence data (website scrapes, enrichment, competitor research). */
+    intelligenceData(params?: {
+        source_type?: string;
+        limit?: number;
+    }): Promise<{
+        data: IntelligenceData[];
+    }>;
+    /** AI research reports (buyer psychology, competitive teardown, GTM channel, etc.). */
+    researchReports(params?: {
+        category?: string;
+        limit?: number;
+    }): Promise<{
+        data: ResearchReport[];
+    }>;
+    /** Create an ICP manually (no AI scoring). Requires name + website_url. */
+    createIcp(body: {
+        name: string;
+        website_url: string;
+        description?: string;
+        firmographics?: Record<string, unknown>;
+        tech_stack?: Record<string, unknown>;
+        buying_signals?: unknown[];
+        estimated_market_size?: number;
+    }): Promise<{
+        data: ICP;
+    }>;
+    /** Update an ICP (partial - send only fields to change). */
+    updateIcp(icpId: string, body: {
+        name?: string;
+        description?: string;
+        firmographics?: Record<string, unknown>;
+        tech_stack?: Record<string, unknown>;
+        buying_signals?: unknown[];
+        estimated_market_size?: number;
+    }): Promise<{
+        data: ICP;
+    }>;
+    /** Archive an ICP (soft delete - sets status to "archived"). */
+    archiveIcp(icpId: string): Promise<{
+        data: ICP;
+    }>;
+    /** Create a buyer persona manually (no AI generation). Requires title + website_url. */
+    createPersona(body: {
+        title: string;
+        website_url: string;
+        priority?: number;
+        confidence?: string;
+        why_target?: string;
+        key_signals?: unknown[];
+        expected_receptivity?: string;
+        campaign_approach?: string;
+        recommended_goal?: string;
+        source?: string;
+    }): Promise<{
+        data: Persona;
+    }>;
+    /** Update a persona (partial). Passing status "archived" is equivalent to archivePersona. */
+    updatePersona(personaId: string, body: {
+        title?: string;
+        priority?: number;
+        confidence?: string;
+        why_target?: string;
+        key_signals?: unknown[];
+        expected_receptivity?: string;
+        campaign_approach?: string;
+        recommended_goal?: string;
+        status?: string;
+    }): Promise<{
+        data: Persona;
+    }>;
+    /** Archive a persona (soft delete - sets status to "archived"). */
+    archivePersona(personaId: string): Promise<{
+        data: Persona;
+    }>;
+};

package/dist/types/tasks.d.ts

@@ -0,0 +1,101 @@
+export interface Task {
+    id: string;
+    entity_type: string | null;
+    entity_id: string | null;
+    title: string;
+    description: string | null;
+    due_date: string | null;
+    assignee_id: string | null;
+    assignee_name: string | null;
+    /** "open" | "completed" (other values may appear if the backend adds states later) */
+    status: string | null;
+    /** 0=none, 1=urgent, 2=high, 3=normal, 4=low */
+    priority: number | null;
+    task_type: string | null;
+    created_by: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+    /** Parent task UUID when this row is a subtask, else null. One level deep. */
+    parent_task_id?: string | null;
+    /** Sort position within the parent's subtasks. 0 when not a subtask. */
+    subtask_sort_order?: number | null;
+    /** Number of subtasks under this task (top-level rows only). */
+    subtask_count?: number | null;
+    /** Subset of subtask_count whose status is "completed". */
+    completed_subtask_count?: number | null;
+}
+export interface TaskCreateParams {
+    title: string;
+    description?: string;
+    /** ISO 8601 date string. */
+    due_date?: string;
+    assignee_id?: string;
+    /** 0=none, 1=urgent, 2=high, 3=normal, 4=low */
+    priority?: number;
+    /**
+     * When set, the new task is created as a subtask of this parent. Parent
+     * must exist and must not itself be a subtask (subtasks are one level
+     * deep).
+     */
+    parent_task_id?: string;
+    /**
+     * Sort position within the parent's subtasks. Omit to append at the end.
+     */
+    subtask_sort_order?: number;
+}
+export interface TaskUpdateParams {
+    title?: string;
+    description?: string;
+    due_date?: string;
+    assignee_id?: string;
+    /** "open" | "completed" */
+    status?: string;
+    priority?: number;
+    /**
+     * Re-parent this task into a subtask of the given parent. Parent must
+     * exist, must not itself be a subtask, and a task that already has
+     * subtasks of its own cannot be demoted into a subtask.
+     */
+    parent_task_id?: string;
+    /** Reorder within the parent's subtasks. Can be sent alone. */
+    subtask_sort_order?: number;
+}
+export interface TaskListParams {
+    /** "open" | "completed" */
+    status?: string;
+    /** 0-4 */
+    priority?: number;
+    assignee_id?: string;
+    /** Substring search on title. */
+    search?: string;
+}
+/**
+ * Tasks API - CRUD for tasks attached to contacts. Requires API key (server-side).
+ *
+ * Backed by:
+ *   GET    /api/v1/contacts/{contact_id}/tasks
+ *   GET    /api/v1/tasks
+ *   POST   /api/v1/contacts/{contact_id}/tasks
+ *   PATCH  /api/v1/tasks/{task_id}
+ *   DELETE /api/v1/tasks/{task_id}
+ */
+export declare const createTasksClient: (apiKey: string, apiUrl?: string) => {
+    /** List tasks on a single contact. Optional status filter ("open" | "completed"). */
+    listForContact(contactId: number, status?: string): Promise<{
+        data: Task[];
+    }>;
+    /** List all tasks org-wide with optional filters. */
+    list(params?: TaskListParams): Promise<{
+        data: Task[];
+    }>;
+    /** Create a task on a contact. */
+    create(contactId: number, task: TaskCreateParams): Promise<Task>;
+    /** Update a task (partial). */
+    update(taskId: string, fields: TaskUpdateParams): Promise<Task>;
+    /** Delete a task. */
+    delete(taskId: string): Promise<{
+        data: {
+            deleted: boolean;
+        };
+    }>;
+};

package/dist/types/types.d.ts

@@ -0,0 +1,45 @@
+/** Configuration for g8.init() */
+export interface G8Config {
+    /** Write key for client-side tracking (from Settings > MCP & API) */
+    writeKey?: string;
+    /** API key for server-side operations (from Settings > MCP & API > API tab) */
+    apiKey?: string;
+    /** Tracking host URL (default: https://t.graph8.com) */
+    host?: string;
+    /** Backend API URL (default: https://be.graph8.com) */
+    apiUrl?: string;
+    /** Privacy controls */
+    privacy?: G8PrivacyConfig;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+export interface G8PrivacyConfig {
+    /** Disable all cookies and event sending */
+    dontSend?: boolean;
+    /** Disable storing user identifiers */
+    dontStoreUserIds?: boolean;
+    /** IP address handling policy */
+    ipPolicy?: "keep" | "stripLastOctet" | "remove";
+}
+/** Properties for g8.track() events */
+export interface TrackProperties {
+    [key: string]: string | number | boolean | null | undefined;
+}
+/** Properties for g8.identify() calls */
+export interface IdentifyProperties {
+    email?: string;
+    name?: string;
+    first_name?: string;
+    last_name?: string;
+    company?: string;
+    company_domain?: string;
+    job_title?: string;
+    phone?: string;
+    [key: string]: string | number | boolean | null | undefined;
+}
+/** Result from g8.forms.lookup() */
+export interface EnrichLookupResult {
+    found: boolean;
+    known_fields: Record<string, string>;
+    missing_fields: string[];
+}

package/dist/types/utils.d.ts

@@ -0,0 +1,21 @@
+/** Check if running on the server (SSR). */
+export declare const isServer: boolean;
+/** Safely get the window object (returns undefined on server). */
+export declare const getWindow: () => Window | undefined;
+/**
+ * Derive the APP origin (which serves the embed pages) from the API origin.
+ *
+ * `apiUrl` addresses the FastAPI backend — `be.graph8.com` in production — and
+ * that host does not serve any page routes: `/webchat/embed` and
+ * `/copilot/embed` are Next.js pages on `app.graph8.com`. The two hosts are
+ * disjoint, so a single base URL cannot address both; an iframe pointed at
+ * `${apiUrl}/webchat/embed` renders the backend's `{"detail":"Not Found"}`.
+ *
+ * This is the inverse of `detectApiBaseUrl` in
+ * `frontend/chat-script/src/config.ts`, which maps `app.` → `be.` to find the
+ * API from the page. Same host convention, read the other way.
+ *
+ * Anything that is not a recognised graph8 or localhost origin is returned
+ * unchanged, so a self-hosted deployment keeps serving both from one host.
+ */
+export declare const resolveAppBaseUrl: (apiBaseUrl: string) => string;

package/dist/types/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The published `@graph8/sdk` version.
+ *
+ * Kept in lock-step with `package.json` by `tests/client-header.test.ts`: bump
+ * both together (the version-parity gate already pins package.json, the
+ * lockfile and the CHANGELOG to each other).
+ */
+export declare const SDK_VERSION = "0.262.0";
+/** Value of the `X-G8-Client` header every SDK request carries (I-13). */
+export declare const SDK_CLIENT_ID = "js-sdk/0.262.0";

package/dist/types/visitors.d.ts

@@ -0,0 +1,29 @@
+export interface VisitorCompany {
+    company_name: string | null;
+    company_domain: string | null;
+    industry: string | null;
+    employee_count: string | null;
+    city: string | null;
+    country: string | null;
+    confidence: number;
+}
+export interface VisitorScore {
+    engagement: number;
+    intent: "low" | "medium" | "high";
+    signals: string[];
+}
+type IntentCallback = (visitor: VisitorCompany & VisitorScore) => void;
+/**
+ * Visitor intelligence - identify anonymous visitors by IP → company.
+ *
+ * Requires write key auth. Works client-side only.
+ */
+export declare const createVisitorsClient: (writeKey: string, apiUrl?: string) => {
+    /** Identify the current visitor's company from their IP address. */
+    identify(): Promise<VisitorCompany>;
+    /** Get engagement score for the current visitor. */
+    score(): Promise<VisitorScore>;
+    /** Listen for visitors matching an intent level. Polls every 30 seconds. */
+    onIntent(level: "low" | "medium" | "high", callback: IntentCallback): () => void;
+};
+export {};

package/dist/types/voice.d.ts

@@ -0,0 +1,304 @@
+type VoiceEvent = "connected" | "transcription" | "ended" | "error";
+type VoiceCallback = (data: Record<string, unknown>) => void;
+export interface VoicePagination {
+    total_items: number;
+    total_pages: number;
+    current_page: number;
+    page_size: number;
+}
+export interface DialerSessionSummary {
+    session_id: string;
+    status: string | null;
+    user_id: string | null;
+    user_email: string | null;
+    org_id: string | null;
+    from_phone: string | null;
+    campaign_id: string | null;
+    campaign_builder_campaign_id: string | null;
+    name: string | null;
+    session_metadata: Record<string, unknown> | null;
+    total_calls: number | null;
+    created_at: string | null;
+    updated_at: string | null;
+    contact_ids: unknown[];
+}
+export interface DialerSessionsListResult {
+    sessions: DialerSessionSummary[];
+    pagination: VoicePagination;
+}
+export interface DialerSessionsListParams {
+    page?: number;
+    /** Default 50, max 200. */
+    page_size?: number;
+    /** Comma-separated status list (e.g. "ACTIVE,PAUSED"). */
+    status?: string;
+    user_email?: string;
+    /** Substring search on session name. */
+    name?: string;
+    campaign_id?: string;
+    list_id?: string;
+    list_name?: string;
+    /** ISO 8601 timestamp. */
+    date_from?: string;
+    /** ISO 8601 timestamp. */
+    date_to?: string;
+    sort_by?: string;
+    /** Default "desc". */
+    sort_order?: "asc" | "desc";
+}
+export interface DialerStatsParams {
+    session_id?: string;
+    user_email?: string;
+    /** YYYY-MM-DD. */
+    date_from?: string;
+    /** YYYY-MM-DD. */
+    date_to?: string;
+    /** Default "DAILY". */
+    aggregation?: "DAILY" | "TOTAL";
+}
+export interface DialerReportFilters {
+    session_id: string | null;
+    user_email: string | null;
+    org_id: string | null;
+    date_from: string | null;
+    date_to: string | null;
+    aggregation: string | null;
+}
+export interface DialerReportMetric {
+    date: string | null;
+    sdr_name: string | null;
+    org_id: string | null;
+    list_title: string | null;
+    total_dials: number;
+    total_connections: number;
+    connection_rate: number;
+    total_voicemails: number;
+    voicemail_rate: number;
+    talk_time_minutes: number;
+    avg_call_duration_minutes: number;
+    dispositions: Record<string, unknown> | null;
+    success_rate: number;
+    unique_sessions: number;
+    avg_calls_per_session: number;
+    redial_count: number;
+    redial_success_rate: number | null;
+    peak_calling_hour: number | null;
+    total_callbacks: number;
+}
+export interface DialerStatsResult {
+    filters: DialerReportFilters;
+    metrics: DialerReportMetric[];
+    summary: DialerReportMetric | null;
+}
+export interface DialerNumberInfo {
+    number: string;
+    /** Default "ai". */
+    inbound_type: string;
+    /** Default "twilio". */
+    telephony_provider: string;
+    calls_today: number;
+    calls_7d: number;
+    connect_rate_7d: number;
+    is_valid: boolean;
+    daily_limit: number;
+    assigned_to: string | null;
+    created_at: string | null;
+}
+export interface DialerNumbersListResult {
+    numbers: DialerNumberInfo[];
+}
+export interface MissedCallback {
+    id: string | number | null;
+    caller_phone: string | null;
+    inbound_number: string | null;
+    first_name: string | null;
+    last_name: string | null;
+    email: string | null;
+    contact_id: string | number | null;
+    parallel_session_id: string | null;
+    created_at: string | null;
+    call_duration: number | null;
+    is_callback: boolean;
+}
+export interface MissedCallbacksResult {
+    missed_callbacks: MissedCallback[];
+    count: number;
+}
+export interface CallGradingResult {
+    room_name: string;
+    /** "ready" or "pending". */
+    status: string;
+    grading: Record<string, unknown> | null;
+    reviewed: boolean;
+    reviewed_at: string | null;
+}
+export interface DialerAgentSummary {
+    agent_id: string;
+    agent_name: string | null;
+    /** "SDR", etc. */
+    role: string | null;
+    agent_status: string | null;
+    /** "agent" or "twin". */
+    entity_type: string | null;
+    description: string | null;
+    phone: string | null;
+    is_template: boolean;
+}
+export interface DialerAgentsListResult {
+    agents: DialerAgentSummary[];
+    total_count: number;
+}
+export interface DialerAgentsListParams {
+    /** e.g. "SDR". */
+    role?: string;
+    agent_status?: string;
+    /** "agent" or "twin". */
+    entity_type?: "agent" | "twin";
+    /** Substring filter on name/description. */
+    search?: string;
+}
+export interface DialerSessionCreateParams {
+    /** 1-200 chars. */
+    name: string;
+    /** Org's dialer phone (E.164, 9-16 chars). */
+    from_phone: string;
+    /** Contact list ID (stored in session metadata). */
+    list_id?: string;
+    /** Display title for the source list. */
+    list_title?: string;
+    /** V2 agent UUID. */
+    agent_id?: string;
+    /** V1 fallback name. Defaults to "default_agent". */
+    agent_name?: string;
+    /** "agent" or "twin". */
+    entity_type?: "agent" | "twin";
+    /** Campaign Builder UUID. */
+    studio_campaign_id?: string;
+    /** IANA timezone (e.g. "America/New_York"). */
+    user_timezone?: string;
+    /** Per-session voicemail-skip override. null/omit = use SDR default. */
+    skip_voicemails?: boolean;
+}
+export interface DialerSessionCreateResult {
+    session_id: string;
+    status: string;
+    name: string | null;
+    org_id: string | null;
+    user_id: string | null;
+    user_email: string | null;
+    from_phone: string | null;
+    session_metadata: Record<string, unknown> | null;
+    total_calls: number;
+    created_at: string | null;
+    message: string | null;
+}
+/** "ACTIVE" resumes, "PAUSED" pauses, "COMPLETED" stops. "FAILED" is rejected. */
+export type DialerSessionStatus = "ACTIVE" | "PAUSED" | "COMPLETED";
+export interface DialerSessionStatusUpdateResult {
+    session_id: string;
+    status: string;
+    message: string | null;
+    name: string | null;
+    org_id: string | null;
+    user_id: string | null;
+    user_email: string | null;
+    from_phone: string | null;
+    session_metadata: Record<string, unknown> | null;
+    total_calls: number;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface DialerSessionResumeResult extends DialerSessionStatusUpdateResult {
+    /** Contacts actually placed in this batch (voice caps at 4). */
+    dialed_count: number;
+}
+/**
+ * Voice AI — start AI voice calls, get transcriptions and analysis.
+ * Plus full parallel-dialer session control via the `dialer` namespace.
+ * Requires API key (server-side).
+ *
+ * Backed by:
+ *   GET    /api/v1/voice/dialer/sessions
+ *   POST   /api/v1/voice/dialer/sessions
+ *   PATCH  /api/v1/voice/dialer/sessions/{session_id}/status
+ *   POST   /api/v1/voice/dialer/sessions/{session_id}/resume
+ *   GET    /api/v1/voice/dialer/stats
+ *   GET    /api/v1/voice/dialer/numbers
+ *   GET    /api/v1/voice/dialer/missed-callbacks
+ *   GET    /api/v1/voice/dialer/calls/{room_name}/grading
+ *   GET    /api/v1/voice/dialer/agents
+ */
+export declare const createVoiceClient: (apiKey: string, apiUrl?: string) => {
+    /** Listen for voice events. */
+    on(event: VoiceEvent, callback: VoiceCallback): void;
+    /** Parallel-dialer session control + analytics. */
+    dialer: {
+        /** List parallel-dialer sessions with filters + pagination. */
+        listSessions(params?: DialerSessionsListParams): Promise<DialerSessionsListResult>;
+        /** Create a parallel-dialer session in PAUSED state. SDR opens UI to start dialing. */
+        createSession(payload: DialerSessionCreateParams): Promise<DialerSessionCreateResult>;
+        /** Pause / resume / stop a dialer session via status flip. */
+        updateSessionStatus(sessionId: string, status: DialerSessionStatus): Promise<DialerSessionStatusUpdateResult>;
+        /**
+         * Resume a PAUSED dialer session.
+         *
+         * @deprecated The server route is retired and answers 410 (it never dialed:
+         * it forwarded to a voice path that did not exist, and the LiveKit dialer it
+         * targeted has been removed). Resume with
+         * `g8.api.call("dial_next_batch_dialer_sessions__session_id__next_batch_post",
+         * { path: { session_id }, body: { resume_intent: true } })`; the rep must have
+         * the dialer open to take the calls.
+         * @param maxContacts 1-4 (voice caps parallel dialing at 4). Default 4.
+         */
+        resumeSession(sessionId: string, maxContacts?: number): Promise<DialerSessionResumeResult>;
+        /** Aggregated dialer analytics (daily breakdown or total). */
+        stats(params?: DialerStatsParams): Promise<DialerStatsResult>;
+        /** List dialer-eligible phone numbers with 7-day stats + daily limits. */
+        numbers(userEmail?: string): Promise<DialerNumbersListResult>;
+        /** List missed inbound callbacks with caller / contact info. */
+        missedCallbacks(limit?: number): Promise<MissedCallbacksResult>;
+        /** AI grading for a single dialer call (returns "pending" while in progress). */
+        callGrading(roomName: string): Promise<CallGradingResult>;
+        /** List voice agents available for dialer sessions (capped at 100; no pagination). */
+        agents(params?: DialerAgentsListParams): Promise<DialerAgentsListResult>;
+        /** Fetch the full transcript for a single dialer call. */
+        callTranscript(roomName: string): Promise<{
+            data: {
+                status: string;
+                transcript: Array<{
+                    speaker: string;
+                    text: string;
+                    timestamp: number;
+                }>;
+            };
+        }>;
+        /** List dialer calls — pass `contact_id` or `user_email` to scope. */
+        listCalls(params?: {
+            contact_id?: number;
+            user_email?: string;
+            campaign_id?: string;
+            date_from?: string;
+            date_to?: string;
+            limit?: number;
+            page?: number;
+        }): Promise<{
+            data: Array<Record<string, unknown>>;
+            pagination?: VoicePagination;
+        }>;
+        /** Convenience: list calls for a single contact. */
+        listCallsForContact(contactId: number, extra?: {
+            limit?: number;
+        }): Promise<{
+            data: Array<Record<string, unknown>>;
+        }>;
+        /** Convenience: list calls placed by a specific SDR. */
+        listCallsForSdr(userEmail: string, extra?: {
+            limit?: number;
+            date_from?: string;
+            date_to?: string;
+        }): Promise<{
+            data: Array<Record<string, unknown>>;
+        }>;
+    };
+};
+export {};