@graph8/sdk 0.251.0 → 0.260.0

package/dist/types/deals.d.ts

@@ -0,0 +1,215 @@
+export interface Deal {
+    /** Canonical CRM revision returned by a conditional update. */
+    revision?: number | null;
+    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;
+}
+export interface DealCreateParams {
+    name: string;
+    /**
+     * Deal owner (user id or email). Required.
+     */
+    owner_id: string;
+    /**
+     * mashup_contact_ids to attach. Required, at least one. Every contact must
+     * belong to the same company, and that company becomes the deal's company.
+     * Same id space as the contacts API. Attach is idempotent.
+     */
+    contact_ids: number[];
+    /**
+     * Deprecated: the company is derived from `contact_ids`. If supplied it must
+     * match the contacts' company, otherwise omit it.
+     */
+    company_id?: number;
+    description?: string;
+    /**
+     * Monetary value. Required (HTTP 400, marker `amount_required_for_won_stage`)
+     * when creating directly in a Closed Won stage; 0 is a valid amount.
+     */
+    amount?: number;
+    /** Default: "USD". */
+    currency?: string;
+    /**
+     * Stage ID from the org's pipelines. Must exist and belong to `pipeline_id`
+     * when both are sent (HTTP 422 otherwise). Defaults to the default
+     * pipeline's first non-closed stage if omitted. Creating directly in a
+     * closed stage triggers the closed-stage rules (HTTP 400 with marker
+     * `close_date_required_for_won_stage` / `close_date_required_for_lost_stage`
+     * / `amount_required_for_won_stage` / `owner_required_for_closed_stage`).
+     */
+    stage_id?: string;
+    /** Pipeline ID. Must exist (HTTP 422 otherwise). Defaults to org's default pipeline if omitted. */
+    pipeline_id?: string;
+    /**
+     * ISO 8601 close date. Required when creating directly in a Closed Won or
+     * Closed Lost stage; past dates are allowed (backdating is supported).
+     */
+    close_date?: string;
+    /**
+     * Set true to create a deal even if one already exists for the company.
+     * By default the API rejects a duplicate with HTTP 409.
+     */
+    allow_duplicate?: boolean;
+}
+export interface DealUpdateParams {
+    /** Require this current CRM revision; a stale edit returns HTTP 409. */
+    expected_revision?: number;
+    name?: string;
+    description?: string;
+    amount?: number;
+    currency?: string;
+    /**
+     * New stage ID. Must be an existing stage in the deal's pipeline (HTTP 422
+     * otherwise). Moving a deal INTO a Closed Won stage requires an effective
+     * close_date AND amount; Closed Lost requires an effective close_date;
+     * either requires an owner ("effective" = the value in this call, else the
+     * deal's existing value). Violations return HTTP 400 with a marker-prefixed
+     * detail: `close_date_required_for_won_stage`,
+     * `close_date_required_for_lost_stage`, `amount_required_for_won_stage`,
+     * `owner_required_for_closed_stage`. Re-submitting the deal's current stage
+     * is never gated.
+     */
+    stage_id?: string;
+    /**
+     * ISO 8601 close date. Explicit null clears it, except on a deal sitting in
+     * a closed stage (HTTP 400, closed-stage markers above).
+     */
+    close_date?: string | null;
+    /**
+     * Reassign the deal owner. Pass a member id, email, or provider uid — it is
+     * resolved to a real team member (HTTP 422 if it matches none). Omit to
+     * leave the owner unchanged. Ownership is reassign-only and CANNOT be
+     * cleared: passing `null` is rejected with HTTP 422 (#18469). A deal's owner
+     * is a required invariant. (The closed-stage gate still applies when moving
+     * into Closed Won/Lost — see `stage_id`.)
+     */
+    owner_id?: string;
+    /**
+     * mashup_contact_ids to link. Must belong to the deal's company (if the deal
+     * has none yet, the added contacts' company is adopted); a cross-company add
+     * is rejected. Idempotent.
+     */
+    add_contact_ids?: number[];
+    /** mashup_contact_ids to unlink. Idempotent. */
+    remove_contact_ids?: number[];
+    /**
+     * Buying-committee role per contact on this deal, keyed by
+     * mashup_contact_id. JSON object keys are strings, so the key type is
+     * `string` even though the id is numeric: `{ "5500429": "champion" }`.
+     * `null` clears a contact's role.
+     *
+     * Applies to contacts already linked to the deal, and to contacts linked by
+     * `add_contact_ids` in the same call (roles are applied after the link). An
+     * id that is neither already linked nor being added is rejected with HTTP
+     * 422 naming the id, and the whole update is rolled back. A role outside the
+     * vocabulary is HTTP 422.
+     */
+    contact_roles?: Record<string, DealContactRole | null>;
+}
+/**
+ * Role a contact plays in a deal's buying committee
+ * (`cb_deal_contacts.role`). The same person can hold different roles on
+ * different deals, so this lives on the deal-contact link, not the contact.
+ */
+export type DealContactRole = "champion" | "decision_maker" | "influencer" | "blocker" | "coach" | "end_user";
+export interface DealListParams {
+    page?: number;
+    limit?: number;
+    stage_id?: string;
+    pipeline_id?: string;
+    /** Substring search on deal name. */
+    search?: string;
+}
+export 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>;
+}
+export interface Pipeline {
+    id: string;
+    name: string;
+    is_default: boolean;
+    stages: PipelineStage[];
+}
+/** Trimmed deal shape returned by /contacts/{id}/deals and /companies/{id}/deals. */
+export 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;
+}
+export 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
+ */
+export 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[];
+    }>;
+};

package/dist/types/enrich.d.ts

@@ -0,0 +1,51 @@
+export interface PersonEnrichment {
+    found: boolean;
+    confidence: number;
+    data: Record<string, unknown>;
+}
+export interface CompanyEnrichment {
+    found: boolean;
+    confidence: number;
+    data: Record<string, unknown>;
+}
+export interface EmailVerification {
+    email: string;
+    valid: boolean;
+    deliverable: boolean;
+    catch_all: boolean;
+}
+export interface SearchFilter {
+    field: string;
+    operator: "any_of" | "contains" | "all_of" | "none_of" | "is_empty" | "is_not_empty" | "between" | "exists";
+    value: unknown;
+}
+export interface SearchResults {
+    contacts: Record<string, unknown>[];
+    total: number;
+    page: number;
+}
+/**
+ * Enrichment API - person/company lookup, email verification, prospecting search.
+ *
+ * Requires API key (server-side only). Credits charged per call. On the hardened
+ * HTTP core: throws a typed `G8Error` on failure and retries transient errors.
+ */
+export declare const createEnrichClient: (apiKey: string, apiUrl?: string) => {
+    /** Look up a person by email, LinkedIn, or name + company. Costs 1 credit. */
+    person(params: {
+        email?: string;
+        linkedin_url?: string;
+        first_name?: string;
+        last_name?: string;
+        company_domain?: string;
+    }): Promise<PersonEnrichment>;
+    /** Look up a company by domain or name. Costs 1 credit. */
+    company(params: {
+        domain?: string;
+        name?: string;
+    }): Promise<CompanyEnrichment>;
+    /** Verify an email address. Costs 1 credit. */
+    verifyEmail(email: string): Promise<EmailVerification>;
+    /** Search 700M+ contacts with filters. Credits charged per result. */
+    search(filters: SearchFilter[], page?: number, limit?: number): Promise<SearchResults>;
+};

package/dist/types/fields.d.ts

@@ -0,0 +1,84 @@
+/** A field (column) definition on contacts or companies — base or custom. */
+export 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). */
+export interface CreatedField {
+    id: number;
+    title: string;
+    data_type: string;
+    name: string;
+    list_id: number | null;
+    is_global: boolean;
+}
+export 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;
+}
+export 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;
+}
+export 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). On the hardened HTTP core: throws a typed
+ * `G8Error` on failure and retries transient errors.
+ *
+ * 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
+ */
+export 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;
+        };
+    }>;
+};

package/dist/types/forms.d.ts

@@ -0,0 +1,16 @@
+import type { EnrichLookupResult } from "./types";
+/**
+ * Progressive form enrichment - checks what fields graph8 already knows
+ * about a contact so your form can skip those fields.
+ *
+ * Calls POST /api/v1/public/enrich/lookup (authenticated via write key).
+ */
+export declare const createFormsClient: (writeKey: string, apiUrl?: string) => {
+    /**
+     * Look up known fields for an email address.
+     *
+     * Use this in progressive forms: after the user enters their email,
+     * check what graph8 already knows and only show missing fields.
+     */
+    lookup(email: string): Promise<EnrichLookupResult>;
+};

package/dist/types/http.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Hardened HTTP core for the graph8 JS SDK (sprint B2).
+ *
+ * Resource clients historically called `fetch` directly and returned
+ * `resp.json()` even on a 4xx/5xx — so API errors surfaced silently as "data".
+ * This module centralizes the request path with:
+ *
+ *   - a typed `G8Error` (status, type, code, request_id, detail) thrown on any
+ *     non-2xx response, parsed from the standard ApiError envelope;
+ *   - automatic retry with exponential backoff + jitter on 429 and 5xx,
+ *     honoring the `Retry-After` header — EXCEPT for billable and external
+ *     (message-sending, call-placing) operations once the request may have
+ *     reached the server (see `isNoBlindRetryOperation`);
+ *   - `Idempotency-Key` on every write (POST/PUT/PATCH/DELETE) the client might
+ *     retry, so a retry collapses into one operation server-side;
+ *   - a cursor `paginate()` async-iterator that follows `next_cursor` (A9).
+ *
+ * `fetch` and `sleep` are injectable so the retry/backoff logic is
+ * deterministically unit-testable without real timers or network.
+ */
+export declare class G8Error extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly code?: string;
+    readonly requestId?: string;
+    readonly detail?: unknown;
+    /** True when the failure class is transient (429/5xx/network). */
+    readonly retryable: boolean;
+    constructor(args: {
+        message: string;
+        status: number;
+        type: string;
+        code?: string;
+        requestId?: string;
+        detail?: unknown;
+        retryable?: boolean;
+    });
+}
+/** 429 and 5xx are the transient classes worth retrying. */
+export declare function isRetryableStatus(status: number): boolean;
+/**
+ * True when `method` + `urlOrPath` is an operation the contract marks
+ * `billable` (it spends credits). Accepts a full URL or a path, with or without
+ * the `/api/v1` base; the query string is ignored.
+ *
+ * The table is generated from the contract (`src/generated/billable.ts`), never
+ * hand-written. Where a concrete path could match both a billable template and
+ * a non-billable one, this answers "billable": the cost of that mistake is a
+ * retry we did not make, while the opposite mistake is a double charge.
+ */
+export declare function isBillableOperation(method: string, urlOrPath: string): boolean;
+/**
+ * True when `method` + `urlOrPath` is an operation the contract marks
+ * `external`: it sends an email, a text or a LinkedIn message, places a phone
+ * call, or launches something that will. Same input rules as
+ * {@link isBillableOperation}; the table is generated into
+ * `src/generated/external.ts`.
+ */
+export declare function isExternalOperation(method: string, urlOrPath: string): boolean;
+/**
+ * True when a failure after the request may have reached the server must NOT be
+ * retried automatically: billable operations (a retry can charge twice) and
+ * external ones (a retry can send the same email or ring the same phone twice).
+ *
+ * Why the server's idempotency key is not enough for `external`: the API keeps
+ * a failed response under its key only for `billable` operations. For every
+ * other tier a 5xx RELEASES the key, so a same-key retry executes again. A send
+ * that reached the provider and then failed on bookkeeping would go out twice.
+ */
+export declare function isNoBlindRetryOperation(method: string, urlOrPath: string): boolean;
+/** True only when the network error provably happened before the request was sent. */
+export declare function isPreSendNetworkError(err: unknown): boolean;
+/**
+ * Parse a `Retry-After` header into milliseconds. Supports both the
+ * delta-seconds form (`"2"`) and the HTTP-date form. Returns null when absent
+ * or unparseable so the caller falls back to computed backoff.
+ */
+export declare function parseRetryAfter(header: string | null | undefined, nowMs?: number): number | null;
+/** Exponential backoff with full jitter, capped at 10s. */
+export declare function backoffDelayMs(attempt: number, baseMs?: number, rand?: () => number): number;
+/**
+ * Record what the server said about a key's agency status. @internal — fed by
+ * `agency.me()` / `agency.clients()`, never by an extra request.
+ */
+export declare function noteAgencyStatus(apiKey: string, isAgency: boolean): void;
+/** @internal Test hook: forget every recorded agency status and warning. */
+export declare function resetAgencyStatusForTests(): void;
+export interface RequestOptions {
+    method?: string;
+    body?: unknown;
+    /**
+     * Extra request headers. Note on `X-Target-Org-Id`: it only takes effect for
+     * an AGENCY key (minted with `is_agency: true`) and only for a client org that
+     * agency is authorized for. For any other key the server silently ignores it
+     * and the call runs against the key's own org; `/api-keys` and `/agency/*`
+     * reject it with a 400. See `agency.me()`.
+     */
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    /**
+     * Sent as the `Idempotency-Key` header. When omitted, one is minted for every
+     * write (POST/PUT/PATCH/DELETE) unless `maxRetries` is 0.
+     */
+    idempotencyKey?: string;
+    /**
+     * Max retry attempts on 429/5xx/network (default 2 -> up to 3 tries).
+     * Billable and external (send / dial / launch) operations are only retried
+     * on 429 and on network errors that provably happened before the request was
+     * sent.
+     */
+    maxRetries?: number;
+    /** Base backoff in ms (default 200). */
+    retryBaseMs?: number;
+    signal?: AbortSignal;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests; defaults to a real setTimeout sleep. */
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+/**
+ * Perform a JSON request with retries + typed errors. Returns the parsed JSON
+ * envelope (callers unwrap `.data` as today). Throws `G8Error` on any non-2xx
+ * after exhausting retries.
+ */
+export declare function request<T = unknown>(baseUrl: string, path: string, apiKey: string, opts?: RequestOptions): Promise<T>;
+/** @internal The identity headers to add, minus any the caller already set. */
+export declare function clientIdentityHeaders(callerHeaders?: Record<string, string>): Record<string, string>;
+export interface PaginatedResponse<T> {
+    data: T[];
+    pagination?: {
+        next_cursor?: string | null;
+        has_next?: boolean;
+        page?: number;
+    };
+}
+/**
+ * Auto-pagination async iterator following `next_cursor` (A9). Yields every
+ * item across pages so callers can `for await (const x of paginate(...))`
+ * without manual cursor bookkeeping.
+ */
+export declare function paginate<T>(fetchPage: (cursor?: string) => Promise<PaginatedResponse<T>>): AsyncGenerator<T, void, unknown>;

package/dist/types/inbox.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Inbox channel — `email`, `sms`, or `linkedin` (HeyReach internally).
+ * Defaults to `email` on routes that accept this as a query param.
+ */
+export type InboxChannel = "email" | "sms" | "linkedin";
+export interface InboxContact {
+    name?: string | null;
+    email?: string | null;
+    company?: string | null;
+    [key: string]: unknown;
+}
+export interface InboxTag {
+    id: string;
+    name: string;
+}
+export interface InboxAssignee {
+    email: string;
+    name?: string | null;
+    [key: string]: unknown;
+}
+export interface InboxMessage {
+    message_id: string | null;
+    from_address: string | null;
+    to_addresses: string[];
+    content: string | null;
+    /** "USER", "AI", or "OTHER". */
+    responder: string | null;
+    date: string | null;
+    is_draft: boolean;
+}
+export interface InboxThread {
+    id: string;
+    /** "email", "sms", or "linkedin". */
+    channel: string;
+    subject: string | null;
+    contact: InboxContact | null;
+    messages: InboxMessage[];
+    /** "open", "responded", "ai_responded", etc. */
+    status: string | null;
+    tags: InboxTag[];
+    assignees: InboxAssignee[];
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface InboxListParams {
+    channel?: InboxChannel;
+    sequence_id?: string;
+    /** Filter by thread status (e.g. "open", "responded", "ai_responded"). */
+    status?: string;
+    /** Filter by assignee email. */
+    assignee?: string;
+    /** Filter by tag ID. */
+    tag?: string;
+    page?: number;
+    /** Default 50, max 100. */
+    page_size?: number;
+}
+export interface InboxAssignResult {
+    assigned: boolean;
+    assignee: string;
+    count: number;
+    [key: string]: unknown;
+}
+export interface InboxTagResult {
+    tagged: boolean;
+    tag_count: number;
+    [key: string]: unknown;
+}
+export interface InboxDraft {
+    /** HTML body. */
+    content: string;
+    /** Plain-text alternative, if available. */
+    plain_content: string | null;
+    /** Credits charged for AI generation. */
+    credits_charged: number;
+}
+export interface InboxSendParams {
+    body: string;
+    channel: InboxChannel;
+    subject?: string;
+    /** Recipient override — email, phone, or LinkedIn ID. */
+    to?: string;
+    /** Sender override — mailbox email, Twilio number, or LinkedIn account ID. */
+    from_address?: string;
+}
+export interface InboxSendResult {
+    message_id: string | null;
+    status: string;
+    channel: string;
+}
+/**
+ * Inbox API — read + reply to multi-channel inbox threads (email, SMS, LinkedIn/HeyReach).
+ * Requires API key (server-side). On the hardened HTTP core: throws a typed
+ * `G8Error` on failure (e.g. 402 when an AI draft exceeds your credit balance)
+ * and retries transient errors.
+ *
+ * Backed by:
+ *   GET   /api/v1/inbox
+ *   GET   /api/v1/inbox/{reply_id}
+ *   POST  /api/v1/inbox/{reply_id}/assign
+ *   POST  /api/v1/inbox/{reply_id}/tag
+ *   GET   /api/v1/inbox/{reply_id}/draft     (charges credits, 402 on insufficient balance)
+ *   POST  /api/v1/inbox/{reply_id}/send
+ */
+export declare const createInboxClient: (apiKey: string, apiUrl?: string) => {
+    /** List inbox threads across email, SMS, and LinkedIn. */
+    list(params?: InboxListParams): Promise<{
+        data: InboxThread[];
+    }>;
+    /** Get a single inbox thread. Defaults to email channel. */
+    get(replyId: string, channel?: InboxChannel): Promise<InboxThread>;
+    /** Assign a user to an inbox thread. */
+    assign(replyId: string, assigneeEmail: string, channel?: InboxChannel): Promise<InboxAssignResult>;
+    /** Attach tag IDs to an inbox thread. */
+    tag(replyId: string, tagIds: string[], channel?: InboxChannel): Promise<InboxTagResult>;
+    /**
+     * Generate an AI draft reply for a thread.
+     * Charges credits — server returns 402 if balance is insufficient.
+     */
+    draft(replyId: string, channel?: InboxChannel): Promise<InboxDraft>;
+    /** Send a reply through email, SMS, or LinkedIn. */
+    send(replyId: string, payload: InboxSendParams): Promise<InboxSendResult>;
+};