@graph8/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,331 @@
 import { AnalyticsInterface } from '@jitsu/js';
 
+interface Deal {
+    id: string | null;
+    name: string | null;
+    description: string | null;
+    amount: number | null;
+    currency: string | null;
+    stage_id: string | null;
+    stage_name: string | null;
+    pipeline_id: string | null;
+    /** Linked company ID (mashup_company_id), if any. */
+    company_id: number | string | null;
+    owner_id: string | null;
+    /** ISO 8601 date. */
+    close_date: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+interface DealCreateParams {
+    name: string;
+    /** Linked company ID. */
+    company_id?: number;
+    description?: string;
+    amount?: number;
+    /** Default: "USD". */
+    currency?: string;
+    /** Stage ID from the org's pipelines. Defaults to first stage of default pipeline if omitted. */
+    stage_id?: string;
+    /** Pipeline ID. Defaults to org's default pipeline if omitted. */
+    pipeline_id?: string;
+    /** ISO 8601 close date. */
+    close_date?: string;
+}
+interface DealUpdateParams {
+    name?: string;
+    description?: string;
+    amount?: number;
+    currency?: string;
+    stage_id?: string;
+    /** ISO 8601 close date. */
+    close_date?: string;
+}
+interface DealListParams {
+    page?: number;
+    limit?: number;
+    stage_id?: string;
+    pipeline_id?: string;
+    /** Substring search on deal name. */
+    search?: string;
+}
+interface PipelineStage {
+    id: string;
+    name: string;
+    probability: number | null;
+    position: number | null;
+    stage_type: string | null;
+    color: string | null;
+    required_elements: string[];
+    recommended_elements: string[];
+    channel_scripts: Record<string, string>;
+}
+interface Pipeline {
+    id: string;
+    name: string;
+    is_default: boolean;
+    stages: PipelineStage[];
+}
+/** Trimmed deal shape returned by /contacts/{id}/deals and /companies/{id}/deals. */
+interface ContactDeal {
+    deal_id: string | null;
+    name: string | null;
+    stage: string | null;
+    value: number | null;
+    currency: string | null;
+    role: string | null;
+    pipeline_id: string | null;
+    close_date: string | null;
+    owner_id: string | null;
+    created_at: string | null;
+}
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    has_next: boolean;
+}
+/**
+ * Deals API - CRUD for deals + pipelines. Requires API key (server-side).
+ *
+ * Backed by:
+ *   GET    /api/v1/deals/pipelines
+ *   GET    /api/v1/deals
+ *   POST   /api/v1/deals
+ *   GET    /api/v1/deals/{deal_id}
+ *   PATCH  /api/v1/deals/{deal_id}
+ *   DELETE /api/v1/deals/{deal_id}
+ *   GET    /api/v1/contacts/{contact_id}/deals
+ *   GET    /api/v1/companies/{company_id}/deals
+ */
+declare const createDealsClient: (apiKey: string, apiUrl?: string) => {
+    /** List all deal pipelines and their stages. */
+    pipelines(): Promise<{
+        data: Pipeline[];
+    }>;
+    /** List deals org-wide with optional filters and pagination. */
+    list(params?: DealListParams): Promise<{
+        data: Deal[];
+        pagination?: PaginationMeta;
+    }>;
+    /** Create a new deal. */
+    create(deal: DealCreateParams): Promise<Deal>;
+    /** Get a single deal by ID. */
+    get(dealId: string): Promise<Deal>;
+    /** Update a deal (partial). */
+    update(dealId: string, fields: DealUpdateParams): Promise<Deal>;
+    /** Delete a deal. */
+    delete(dealId: string): Promise<{
+        data: {
+            deleted: boolean;
+        };
+    }>;
+    /** Get all deals associated with a contact. */
+    forContact(contactId: number): Promise<{
+        data: ContactDeal[];
+    }>;
+    /** Get all deals associated with a company. */
+    forCompany(companyId: number): Promise<{
+        data: ContactDeal[];
+    }>;
+};
+
+/** A field (column) definition on contacts or companies — base or custom. */
+interface Field {
+    id: number | null;
+    title: string;
+    /** Internal column name (slug). */
+    name: string | null;
+    /** Currently only "text" is supported; other types may be added later. */
+    data_type: string;
+    /** True if available org-wide, false if list-specific. */
+    is_global: boolean;
+}
+/** Created custom field (column). */
+interface CreatedField {
+    id: number;
+    title: string;
+    data_type: string;
+    name: string;
+    list_id: number | null;
+    is_global: boolean;
+}
+interface FieldCreateParams {
+    title: string;
+    /** "contacts" or "companies". Defaults to "contacts" on the backend. */
+    entity?: "contacts" | "companies";
+    /** "text" (default) — additional types may be added later. */
+    data_type?: string;
+    /** If set, the field is list-specific. Omit for org-wide global field. */
+    list_id?: number;
+}
+interface FieldDeleteParams {
+    entity?: "contacts" | "companies";
+    /**
+     * Optional list scope guard. If provided, the column must belong to this
+     * list or the request returns 404. Use this to prevent accidentally
+     * deleting a column on a different list in the same org.
+     */
+    list_id?: number;
+}
+interface SetFieldValueParams {
+    /** Contact ID (entity='contacts') or company ID (entity='companies'). */
+    record_id: number;
+    /** Value to write. Pass null/undefined to clear the field. */
+    value?: string | null;
+    entity?: "contacts" | "companies";
+}
+/**
+ * Fields API - manage custom fields (columns) on contacts and companies.
+ * Requires API key (server-side).
+ *
+ * Backed by:
+ *   GET    /api/v1/fields                — list contact fields
+ *   GET    /api/v1/fields/companies      — list company fields
+ *   POST   /api/v1/fields                — create a custom field
+ *   DELETE /api/v1/fields/{column_id}    — delete a custom field
+ *   PATCH  /api/v1/fields/{column_id}/values — set value on a single record
+ */
+declare const createFieldsClient: (apiKey: string, apiUrl?: string) => {
+    /** List contact fields (base + custom). Pass listId to include list-specific custom fields. */
+    listContactFields(listId?: number): Promise<{
+        data: Field[];
+    }>;
+    /** List company fields (base + custom). Pass listId to include list-specific custom fields. */
+    listCompanyFields(listId?: number): Promise<{
+        data: Field[];
+    }>;
+    /** Create a custom field on contacts (default) or companies. */
+    create(params: FieldCreateParams): Promise<CreatedField>;
+    /** Delete a custom field (soft-delete). Pass list_id to scope-guard against cross-list deletion. */
+    delete(columnId: number, params?: FieldDeleteParams): Promise<{
+        data: {
+            column_id: number;
+            deleted: boolean;
+        };
+    }>;
+    /** Set a custom field value on a single contact or company row. Pass value=null to clear. */
+    setValue(columnId: number, params: SetFieldValueParams): Promise<{
+        data: {
+            column_id: number;
+            record_id: number;
+            updated: boolean;
+        };
+    }>;
+};
+
+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;
+}
+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;
+}
+interface TaskUpdateParams {
+    title?: string;
+    description?: string;
+    due_date?: string;
+    assignee_id?: string;
+    /** "open" | "completed" */
+    status?: string;
+    priority?: number;
+}
+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}
+ */
+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;
+        };
+    }>;
+};
+
+interface Note {
+    id: string;
+    entity_type: string;
+    entity_id: string;
+    content: string;
+    created_by: string | null;
+    created_by_name: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+/**
+ * Notes API - CRUD for notes attached to contacts. Requires API key (server-side).
+ *
+ * Backed by:
+ *   GET    /api/v1/contacts/{contact_id}/notes
+ *   POST   /api/v1/contacts/{contact_id}/notes
+ *   PATCH  /api/v1/notes/{note_id}
+ *   DELETE /api/v1/notes/{note_id}
+ */
+declare const createNotesClient: (apiKey: string, apiUrl?: string) => {
+    /** List all notes on a contact. */
+    list(contactId: number): Promise<{
+        data: Note[];
+    }>;
+    /** Create a note on a contact. */
+    create(contactId: number, content: string): Promise<Note>;
+    /** Update a note's content. */
+    update(noteId: string, content: string): Promise<Note>;
+    /** Delete a note. */
+    delete(noteId: string): Promise<{
+        data: {
+            deleted: boolean;
+        };
+    }>;
+};
+
 interface ContactList {
     id: number;
     title: string;
@@ -84,6 +410,25 @@ interface CompanyContact {
     work_email: string | null;
     job_title: string | null;
 }
+/** A column definition on companies (base or custom). */
+interface CompanyColumn {
+    id: number | null;
+    title: string;
+    data_type: string;
+    name: string | null;
+    /** Stringified list_id when list-scoped, otherwise null/empty for global. */
+    object_id: string | null;
+    is_global: boolean;
+}
+interface CompanyColumnCreateParams {
+    title: string;
+    /** Email of the user creating the column. Required by the backend (audit). */
+    created_by: string;
+    /** "text" (default) — additional types may be added later. */
+    data_type?: string;
+    /** If set, the column is list-specific. Omit for org-wide global column. */
+    list_id?: number;
+}
 /**
  * Companies API - search and manage CRM companies. Requires API key (server-side).
  */
@@ -108,6 +453,12 @@ declare const createCompaniesClient: (apiKey: string, apiUrl?: string) => {
     delete(companyId: number): Promise<{
         deleted: boolean;
     }>;
+    /** List custom company columns. Pass listId to include list-specific columns. */
+    listColumns(listId?: number): Promise<{
+        data: CompanyColumn[];
+    }>;
+    /** Create a custom company column. Global if list_id is omitted, list-scoped otherwise. */
+    createColumn(params: CompanyColumnCreateParams): Promise<CompanyColumn>;
 };
 
 interface Contact {
@@ -164,6 +515,25 @@ interface ContactUpdateParams {
     state?: string;
     country?: string;
 }
+/** A column definition on contacts (base or custom). */
+interface ContactColumn {
+    id: number | null;
+    title: string;
+    data_type: string;
+    name: string | null;
+    /** Stringified list_id when list-scoped, otherwise null/empty for global. */
+    object_id: string | null;
+    is_global: boolean;
+}
+interface ContactColumnCreateParams {
+    title: string;
+    /** Email of the user creating the column. Required by the backend (audit). */
+    created_by: string;
+    /** "text" (default) — additional types may be added later. */
+    data_type?: string;
+    /** If set, the column is list-specific. Omit for org-wide global column. */
+    list_id?: number;
+}
 /**
  * Contacts API - full CRUD for CRM contacts. Requires API key (server-side).
  */
@@ -185,6 +555,12 @@ declare const createContactsClient: (apiKey: string, apiUrl?: string) => {
     delete(contactId: number): Promise<{
         deleted: boolean;
     }>;
+    /** List custom contact columns. Pass listId to include list-specific columns. */
+    listColumns(listId?: number): Promise<{
+        data: ContactColumn[];
+    }>;
+    /** Create a custom contact column. Global if list_id is omitted, list-scoped otherwise. */
+    createColumn(params: ContactColumnCreateParams): Promise<ContactColumn>;
 };
 
 type WebhookEvent = "reply_received" | "meeting_booked" | "contact_enriched" | "contact_created" | "sequence_completed" | "sequence_replied" | "campaign_launched" | "form_submitted" | "visitor_identified";
@@ -664,6 +1040,10 @@ declare class G8 {
     /** @internal */ _contacts: ReturnType<typeof createContactsClient> | null;
     /** @internal */ _companies: ReturnType<typeof createCompaniesClient> | null;
     /** @internal */ _lists: ReturnType<typeof createListsClient> | null;
+    /** @internal */ _notes: ReturnType<typeof createNotesClient> | null;
+    /** @internal */ _tasks: ReturnType<typeof createTasksClient> | null;
+    /** @internal */ _fields: ReturnType<typeof createFieldsClient> | null;
+    /** @internal */ _deals: ReturnType<typeof createDealsClient> | null;
     /**
      * Initialize the graph8 SDK. Must be called before any other method.
      * Safe to call on the server (SSR) - becomes a no-op for tracking.
@@ -804,6 +1184,10 @@ declare class G8 {
         delete(contactId: number): Promise<{
             deleted: boolean;
         }>;
+        listColumns(listId?: number): Promise<{
+            data: ContactColumn[];
+        }>;
+        createColumn(params: ContactColumnCreateParams): Promise<ContactColumn>;
     };
     /** Companies CRUD (requires API key). */
     get companies(): {
@@ -822,6 +1206,10 @@ declare class G8 {
         delete(companyId: number): Promise<{
             deleted: boolean;
         }>;
+        listColumns(listId?: number): Promise<{
+            data: CompanyColumn[];
+        }>;
+        createColumn(params: CompanyColumnCreateParams): Promise<CompanyColumn>;
     };
     /** Lists management (requires API key). */
     get lists(): {
@@ -844,6 +1232,82 @@ declare class G8 {
             removed: number;
         }>;
     };
+    /** Notes on contacts (requires API key). */
+    get notes(): {
+        list(contactId: number): Promise<{
+            data: Note[];
+        }>;
+        create(contactId: number, content: string): Promise<Note>;
+        update(noteId: string, content: string): Promise<Note>;
+        delete(noteId: string): Promise<{
+            data: {
+                deleted: boolean;
+            };
+        }>;
+    };
+    /** Tasks on contacts (requires API key). */
+    get tasks(): {
+        listForContact(contactId: number, status?: string): Promise<{
+            data: Task[];
+        }>;
+        list(params?: TaskListParams): Promise<{
+            data: Task[];
+        }>;
+        create(contactId: number, task: TaskCreateParams): Promise<Task>;
+        update(taskId: string, fields: TaskUpdateParams): Promise<Task>;
+        delete(taskId: string): Promise<{
+            data: {
+                deleted: boolean;
+            };
+        }>;
+    };
+    /** Custom fields management (requires API key). */
+    get fields(): {
+        listContactFields(listId?: number): Promise<{
+            data: Field[];
+        }>;
+        listCompanyFields(listId?: number): Promise<{
+            data: Field[];
+        }>;
+        create(params: FieldCreateParams): Promise<CreatedField>;
+        delete(columnId: number, params?: FieldDeleteParams): Promise<{
+            data: {
+                column_id: number;
+                deleted: boolean;
+            };
+        }>;
+        setValue(columnId: number, params: SetFieldValueParams): Promise<{
+            data: {
+                column_id: number;
+                record_id: number;
+                updated: boolean;
+            };
+        }>;
+    };
+    /** Deals and pipelines (requires API key). */
+    get deals(): {
+        pipelines(): Promise<{
+            data: Pipeline[];
+        }>;
+        list(params?: DealListParams): Promise<{
+            data: Deal[];
+            pagination?: PaginationMeta;
+        }>;
+        create(deal: DealCreateParams): Promise<Deal>;
+        get(dealId: string): Promise<Deal>;
+        update(dealId: string, fields: DealUpdateParams): Promise<Deal>;
+        delete(dealId: string): Promise<{
+            data: {
+                deleted: boolean;
+            };
+        }>;
+        forContact(contactId: number): Promise<{
+            data: ContactDeal[];
+        }>;
+        forCompany(companyId: number): Promise<{
+            data: ContactDeal[];
+        }>;
+    };
     /** Whether the SDK has been initialized. */
     get initialized(): boolean;
     /** @internal */
@@ -854,4 +1318,4 @@ declare class G8 {
 /** Singleton g8 client instance. */
 declare const g8: G8;
 
-export { type AddToSequenceConfig, type AnalyticsOverview, type Booking, type BookingRequest, type CalendarConfig, type CallAnalysis, type Campaign, type CampaignCreateConfig, type CampaignStats, type ChatConfig, type Company, type CompanyContact, type CompanyEnrichment, type CompanyListParams, type CompanyUpdateParams, type Contact, type ContactCreateParams, type ContactList, type ContactListParams, type ContactUpdateParams, type CopilotConfig, type EmailVerification, type EnrichLookupResult, type G8Config, type G8PrivacyConfig, type IdentifyProperties, type Integration, type IntentSignals, type LandingPage, type ListContact, type PersonEnrichment, type SearchFilter, type SearchResults, type Sequence, type TimeSlot, type TrackProperties, type VisitorCompany, type VisitorScore, type VoiceSession, type WebhookEvent, g8 };
+export { type AddToSequenceConfig, type AnalyticsOverview, type Booking, type BookingRequest, type CalendarConfig, type CallAnalysis, type Campaign, type CampaignCreateConfig, type CampaignStats, type ChatConfig, type Company, type CompanyColumn, type CompanyColumnCreateParams, type CompanyContact, type CompanyEnrichment, type CompanyListParams, type CompanyUpdateParams, type Contact, type ContactColumn, type ContactColumnCreateParams, type ContactCreateParams, type ContactDeal, type ContactList, type ContactListParams, type ContactUpdateParams, type CopilotConfig, type CreatedField, type Deal, type DealCreateParams, type DealListParams, type DealUpdateParams, type EmailVerification, type EnrichLookupResult, type Field, type FieldCreateParams, type FieldDeleteParams, type G8Config, type G8PrivacyConfig, type IdentifyProperties, type Integration, type IntentSignals, type LandingPage, type ListContact, type Note, type PaginationMeta, type PersonEnrichment, type Pipeline, type PipelineStage, type SearchFilter, type SearchResults, type Sequence, type SetFieldValueParams, type Task, type TaskCreateParams, type TaskListParams, type TaskUpdateParams, type TimeSlot, type TrackProperties, type VisitorCompany, type VisitorScore, type VoiceSession, type WebhookEvent, g8 };