@graph8/sdk 0.251.0 → 0.262.0

package/dist/types/contacts.d.ts

@@ -0,0 +1,200 @@
+export interface Contact {
+    id: number;
+    first_name: string | null;
+    last_name: string | null;
+    work_email: string | null;
+    job_title: string | null;
+    seniority_level: string | null;
+    company_name: string | null;
+    company_domain: string | null;
+    linkedin_url: string | null;
+    direct_phone: string | null;
+    mobile_phone: string | null;
+    city: string | null;
+    state: string | null;
+    country: string | null;
+}
+export interface ContactListParams {
+    page?: number;
+    limit?: number;
+    email?: string;
+    name?: string;
+    job_title?: string;
+    seniority_level?: string;
+    company_name?: string;
+    country?: string;
+    list_id?: number;
+}
+export interface ContactCreateParams {
+    work_email: string;
+    first_name?: string;
+    last_name?: string;
+    job_title?: string;
+    company_domain?: string;
+    linkedin_url?: string;
+    direct_phone?: string;
+    mobile_phone?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    list_id?: number;
+}
+export interface ContactUpdateParams {
+    first_name?: string;
+    last_name?: string;
+    work_email?: string;
+    job_title?: string;
+    company_domain?: string;
+    linkedin_url?: string;
+    direct_phone?: string;
+    mobile_phone?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+}
+/**
+ * Fields for `contacts.upsert()` (`PUT /api/v1/contacts/assert`).
+ * Matches an existing contact by `work_email`, then `linkedin_url`; at least
+ * one is required. `list_id` is required: the contact is created in, or
+ * updated and kept in, that list.
+ */
+export interface ContactUpsertParams {
+    list_id: number;
+    work_email?: string;
+    linkedin_url?: string;
+    first_name?: string;
+    last_name?: string;
+    personal_emails?: string;
+    direct_phone?: string;
+    mobile_phone?: string;
+    job_title?: string;
+    job_department?: string;
+    seniority_level?: string;
+    city?: string;
+    state?: string;
+    country?: string;
+    company_domain?: string;
+    /** Custom (dynamic) columns, keyed by title or `udo_*` slug. */
+    custom_fields?: Record<string, string | null>;
+    /** Create a custom column that does not exist yet instead of skipping it. */
+    create_missing_fields?: boolean;
+}
+/** Result of `contacts.upsert()`. */
+/**
+ * The full contact record: what `get()` and `getMany()` return. `list()` returns
+ * the leaner `Contact`; these are the fields only the full record carries.
+ */
+export interface ContactDetail extends Contact {
+    full_name?: string | null;
+    personal_emails?: string | null;
+    about?: string | null;
+    company?: Record<string, unknown> | null;
+    confidence_score?: number | null;
+    twitter_url?: string | null;
+    facebook_url?: string | null;
+    meta_data?: Record<string, unknown> | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    custom_fields?: Record<string, unknown>;
+}
+/** One entry of `getMany()`: the full record, or `found: false`. */
+export interface ContactBulkGetItem {
+    contact_id: number;
+    /** False when the contact does not exist or is outside this key's scope. */
+    found: boolean;
+    contact: ContactDetail | null;
+}
+/** `POST /contacts/bulk-get` accepts at most this many ids; `getMany()` splits larger inputs. */
+export declare const CONTACT_BULK_GET_MAX = 100;
+export interface ContactUpsertResult {
+    /** "created" when no contact matched, "updated" when one did. */
+    action: "created" | "updated" | string;
+    count: number;
+    /** How the call handled `custom_fields` keys (resolved / created / skipped). */
+    custom_fields?: Record<string, unknown>;
+}
+/** A column definition on contacts (base or custom). */
+export 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;
+}
+export 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).
+ */
+export declare const createContactsClient: (apiKey: string, apiUrl?: string) => {
+    /** List contacts with optional filters. */
+    list(params?: ContactListParams): Promise<{
+        data: Contact[];
+        total: number;
+    }>;
+    /**
+     * Full records for many contacts (`POST /api/v1/contacts/bulk-get`), in input
+     * order. Any number of ids: they are sent 100 per request, so 1,000 ids cost
+     * 10 requests instead of 1,000 `get()` calls. Missing or out-of-scope ids come
+     * back `found: false` rather than throwing. Duplicate ids are read once.
+     */
+    getMany: (contactIds: number[], options?: {
+        includeCustomFields?: boolean;
+    }) => Promise<ContactBulkGetItem[]>;
+    /**
+     * One page of `list()`, with every contact's FULL record (`created_at`,
+     * `updated_at`, `full_name`, `personal_emails`, `company`, ...). `list()`
+     * returns a leaner shape. Costs one `list()` request plus one `getMany()`
+     * request per 100 contacts on the page. `missing` holds ids that were listed
+     * but could not be read (for example deleted in between).
+     */
+    listDetailed(params?: ContactListParams, options?: {
+        includeCustomFields?: boolean;
+    }): Promise<{
+        data: ContactDetail[];
+        total: number;
+        missing: number[];
+    }>;
+    /** Get a single contact by ID. */
+    get(contactId: number): Promise<Contact>;
+    /**
+     * Create a new contact. Pass `idempotencyKey` to make a retry safe — the
+     * same key returns the first result instead of creating a duplicate (A6).
+     *
+     * Create-only: if a contact with the same work_email / linkedin_url exists,
+     * this throws a 409 `G8Error` whose `detail.hint` / `detail.upsert` name the
+     * create-or-update route. When the contact may already exist, use `upsert()`.
+     */
+    create(contact: ContactCreateParams, idempotencyKey?: string): Promise<Contact>;
+    /**
+     * Create or update a contact in one idempotent call (`PUT /contacts/assert`).
+     * Matches by `work_email`, then `linkedin_url`. Prefer this over `create()`
+     * when the contact may already exist: `create()` returns a 409 for a
+     * duplicate, while `upsert()` updates it. Safe to retry. The server answers
+     * 400 (a `G8Error`) when neither `work_email` nor `linkedin_url` is given.
+     */
+    upsert(contact: ContactUpsertParams): Promise<ContactUpsertResult>;
+    /** Update a contact (partial). */
+    update(contactId: number, fields: ContactUpdateParams): Promise<{
+        updated: number;
+    }>;
+    /** Delete a contact (soft-delete). */
+    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>;
+};

package/dist/types/copilot.d.ts

@@ -0,0 +1,31 @@
+export interface CopilotConfig {
+    /** Initial greeting message */
+    greeting?: string;
+    /** Context passed to the AI */
+    context?: Record<string, unknown>;
+    /** Widget position */
+    position?: "bottom-right" | "bottom-left";
+    /** Widget theme */
+    theme?: "light" | "dark" | "auto";
+}
+type CopilotEvent = "message" | "tool_used" | "open" | "close" | "error";
+type CopilotCallback = (data: Record<string, unknown>) => void;
+type ActionHandler = (params: Record<string, unknown>) => void | Promise<void>;
+/**
+ * Copilot - embeddable AI assistant with org knowledge base access.
+ *
+ * Client-side (write key) for the widget embed.
+ */
+export declare const createCopilotClient: (writeKey: string, apiUrl?: string) => {
+    /** Open the copilot widget. */
+    open(config?: CopilotConfig): void;
+    /** Send a message to the copilot programmatically. */
+    ask(message: string): Promise<string>;
+    /** Register a custom action the copilot can trigger. */
+    registerAction(name: string, handler: ActionHandler): void;
+    /** Listen for copilot events. */
+    on(event: CopilotEvent, callback: CopilotCallback): void;
+    /** Close the copilot widget. */
+    close(): void;
+};
+export {};