@graph8/sdk 0.5.3 → 0.7.2

package/dist/index.d.mts

@@ -1,5 +1,313 @@
 import { AnalyticsInterface } from '@jitsu/js';
 
+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`.
+ */
+declare const createSnippetClient: (apiKey: string, apiUrl?: string) => {
+    /** Get your org's tracking snippet (write key + React/script-tag embeds + config). */
+    get(): Promise<Snippet>;
+};
+
+interface MarketplaceProfile {
+    id: string;
+    email: string;
+    first_name?: string | null;
+    last_name?: string | null;
+    marketplace_role?: string | null;
+    country_code?: string | null;
+    monthly_rate_usd?: string | null;
+    per_meeting_rate_usd?: string | null;
+    availability_status?: string | null;
+    bio?: string | null;
+    is_complete: boolean;
+}
+interface MarketplaceOffer {
+    id: string;
+    org_id: string;
+    org_name?: string | null;
+    sdr_id: string;
+    status: string;
+    monthly_rate_usd?: string | null;
+    per_meeting_rate_usd?: string | null;
+    created_at?: string | null;
+}
+interface MarketplaceHiring {
+    id: string;
+    org_id: string;
+    sdr_id: string;
+    status: string;
+    sdr_name?: string | null;
+    sdr_role?: string | null;
+    sdr_email?: string | null;
+    monthly_rate_usd?: string | null;
+    per_meeting_rate_usd?: string | null;
+    started_at?: string | null;
+}
+/**
+ * Marketplace API — for SDR/AE talent on the graph8 marketplace. View your
+ * profile, see pending hire offers and respond to them, and list your active
+ * hirings. Requires a personal 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/marketplace`.
+ */
+declare const createMarketplaceClient: (apiKey: string, apiUrl?: string) => {
+    /** Your own marketplace SDR profile. */
+    profile(): Promise<MarketplaceProfile>;
+    /** Pending hire offers you can accept or reject. */
+    offers(): Promise<{
+        offers: MarketplaceOffer[];
+        count: number;
+    }>;
+    /** Accept a pending hire offer (by hiring id). */
+    acceptOffer(hiringId: string): Promise<Record<string, unknown>>;
+    /** Reject a pending hire offer (by hiring id). */
+    rejectOffer(hiringId: string): Promise<Record<string, unknown>>;
+    /** Your active hiring contracts. */
+    hirings(): Promise<{
+        hirings: MarketplaceHiring[];
+        count: number;
+    }>;
+};
+
+interface AgencyInfo {
+    agency_org_id: string;
+    agency_org_name: string | null;
+    is_agency: boolean;
+    client_count: number;
+    /** Request header to set when operating a client org (e.g. "X-Target-Org-Id"). */
+    target_header: string;
+}
+interface AgencyClient {
+    /** Pass this as the `X-Target-Org-Id` header to operate this client org. */
+    org_id: string;
+}
+/**
+ * Agency API — for agency-scoped API keys (minted with `is_agency: true`).
+ * Discover the agency credential and the client orgs it may operate. To act on a
+ * client org, set the `X-Target-Org-Id` header (see `target_header`) to that
+ * client's `org_id` on your subsequent requests. Requires an agency API key
+ * (server-side); a non-agency key gets a `403`.
+ *
+ * Built on the hardened HTTP core (typed `G8Error` + retries). Backed by
+ * `/api/v1/agency`.
+ */
+declare const createAgencyClient: (apiKey: string, apiUrl?: string) => {
+    /** Describe the agency credential: agency org + authorized client count. */
+    me(): Promise<AgencyInfo>;
+    /** List the client orgs this agency key may target via `X-Target-Org-Id`. */
+    clients(): Promise<{
+        data: AgencyClient[];
+    }>;
+};
+
+/** Filter operators supported by open-data search. */
+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`). */
+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[];
+}
+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;
+}
+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;
+}
+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;
+}
+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;
+}
+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`.
+ */
+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>;
+};
+
+/** Ad platform an audience can sync to. */
+type AudienceSyncPlatform = "meta" | "linkedin" | "google" | "x";
+/** Sync mode: full mirror, or only ever add members. */
+type AudienceSyncMode = "mirror" | "append_only";
+interface AudienceSync {
+    id: number;
+    audience_id: number;
+    platform: string;
+    platform_audience_name: string | null;
+    mode: string;
+    refresh_cadence_hours: number;
+    is_active: boolean;
+    status: string | null;
+    last_sync_at: string | null;
+    created_at: string | null;
+}
+interface AudienceSyncCreateParams {
+    /** Audience list ID to sync. */
+    audience_id: number;
+    platform: AudienceSyncPlatform;
+    platform_audience_name?: string;
+    /** Default "mirror". */
+    mode?: AudienceSyncMode;
+    /** Refresh cadence in hours (0-720; default 24). */
+    refresh_cadence_hours?: number;
+    /** Platform-specific config (OAuth creds, ad-account ids, etc.). */
+    platform_config?: Record<string, unknown>;
+    /** Audience list IDs whose members should be suppressed from the sync. */
+    suppression_list_ids?: number[];
+}
+interface AudienceSyncUpdateParams {
+    mode?: AudienceSyncMode;
+    refresh_cadence_hours?: number;
+    is_active?: boolean;
+    suppression_list_ids?: number[];
+}
+interface AudienceSyncRun {
+    id: number;
+    started_at: string | null;
+    finished_at: string | null;
+    status: string | null;
+    members_added: number | null;
+    members_removed: number | null;
+    total_members: number | null;
+    error_message: string | null;
+}
+interface AudienceSyncError {
+    id: number;
+    started_at: string | null;
+    error_message: string | null;
+    details: Record<string, unknown> | null;
+}
+/**
+ * Audiences API — sync an audience list to ad platforms (Meta, LinkedIn,
+ * Google, X). Requires API key (server-side). Built on the hardened HTTP core,
+ * so every method throws a typed `G8Error` on failure and retries transient
+ * 429/5xx/network errors.
+ *
+ * Backed by `/api/v1/audience-syncs`.
+ */
+declare const createAudiencesClient: (apiKey: string, apiUrl?: string) => {
+    /** List all audience syncs for the organization. */
+    list(): Promise<{
+        data: AudienceSync[];
+    }>;
+    /** Create a new audience sync to an ad platform. */
+    create(params: AudienceSyncCreateParams): Promise<AudienceSync>;
+    /** Get a single audience sync by ID. */
+    get(configId: number): Promise<AudienceSync>;
+    /** Update an audience sync (partial). */
+    update(configId: number, fields: AudienceSyncUpdateParams): Promise<AudienceSync>;
+    /** Delete an audience sync. */
+    delete(configId: number): Promise<{
+        data: Record<string, unknown>;
+    }>;
+    /** Trigger an immediate sync run for a config. */
+    trigger(configId: number): Promise<{
+        data: Record<string, unknown>;
+    }>;
+    /** List recent sync runs for a config (most recent first). */
+    runs(configId: number): Promise<{
+        data: AudienceSyncRun[];
+    }>;
+    /** List recent sync errors for a config. */
+    errors(configId: number): Promise<{
+        data: AudienceSyncError[];
+    }>;
+};
+
 interface MeetingAttendee {
     name: string | null;
     email: string;
@@ -585,7 +893,8 @@ interface WorkflowListParams {
 }
 /**
  * Workflows API - automation workflows with nodes, connections, and execution lifecycle.
- * Requires API key (server-side).
+ * Requires API key (server-side). On the hardened HTTP core: throws a typed
+ * `G8Error` on failure and retries transient errors.
  *
  * The graph8 workflow surface treats the whole workflow definition as a single
  * record updated via `update()` — there are no per-node CRUD endpoints. To edit
@@ -650,9 +959,9 @@ declare const createWorkflowsClient: (apiKey: string, apiUrl?: string) => {
     }>;
     /** Execute a workflow immediately with a trigger payload. */
     execute(workflowId: string, triggerPayload?: Record<string, unknown>): Promise<WorkflowExecution>;
-    /** Get the status + output of a workflow execution. */
+    /** Get the status + outputs of a single execution. */
     getExecution(executionId: string): Promise<WorkflowExecution>;
-    /** Pause an in-flight execution. */
+    /** Pause a running execution. */
     pauseExecution(executionId: string): Promise<{
         data: {
             paused: boolean;
@@ -664,34 +973,32 @@ declare const createWorkflowsClient: (apiKey: string, apiUrl?: string) => {
             resumed: boolean;
         };
     }>;
-    /** Stop an execution (terminal state — cannot resume). */
+    /** Stop an execution. */
     stopExecution(executionId: string): Promise<{
         data: {
             stopped: boolean;
         };
     }>;
-    /** Get the status of a workflow's external trigger (e.g. "waiting for webhook"). */
+    /** Get the trigger status (e.g. schedule / webhook wiring) for a workflow. */
     getTriggerStatus(workflowId: string): Promise<{
         data: {
             status: string;
             details: Record<string, unknown>;
         };
     }>;
-    /** Reset the trigger cursor (e.g. for event-stream triggers — resume from beginning). */
+    /** Reset a workflow's trigger cursor / state. */
     resetTrigger(workflowId: string): Promise<{
         data: {
             reset: boolean;
         };
     }>;
-    /**
-     * List available node types with schemas. Pass a `type` param to fetch one type's full schema.
-     */
+    /** Catalog of available workflow node types with config + output schemas. */
     nodeTypes(params?: {
         type?: string;
     }): Promise<{
         data: NodeTypeSchema[];
     }>;
-    /** Slack workspace users (for Slack action recipients). */
+    /** Slack users available to workflow nodes. */
     listSlackUsers(): Promise<{
         data: Array<{
             id: string;
@@ -699,7 +1006,7 @@ declare const createWorkflowsClient: (apiKey: string, apiUrl?: string) => {
             email: string | null;
         }>;
     }>;
-    /** Slack channels. */
+    /** Slack channels available to workflow nodes. */
     listSlackChannels(): Promise<{
         data: Array<{
             id: string;
@@ -707,7 +1014,7 @@ declare const createWorkflowsClient: (apiKey: string, apiUrl?: string) => {
             is_private: boolean;
         }>;
     }>;
-    /** Roam (Copilot chat) users. */
+    /** Roam users available to workflow nodes. */
     listRoamUsers(): Promise<{
         data: Array<{
             id: string;
@@ -715,14 +1022,14 @@ declare const createWorkflowsClient: (apiKey: string, apiUrl?: string) => {
             email: string | null;
         }>;
     }>;
-    /** Roam (Copilot chat) groups. */
+    /** Roam groups available to workflow nodes. */
     listRoamGroups(): Promise<{
         data: Array<{
             id: string;
             name: string;
         }>;
     }>;
-    /** Available MCP servers (for Agent-node integrations). */
+    /** MCP servers available to workflow nodes. */
     listMcpServers(): Promise<{
         data: Array<{
             id: string;
@@ -730,14 +1037,14 @@ declare const createWorkflowsClient: (apiKey: string, apiUrl?: string) => {
             url: string;
         }>;
     }>;
-    /** Available call dispositions (voice workflow nodes). */
+    /** Disposition options available to workflow nodes. */
     listDispositions(): Promise<{
         data: Array<{
             id: string;
             label: string;
         }>;
     }>;
-    /** Form field schema for form-trigger nodes. */
+    /** Form field definitions for a given form (used by form-trigger nodes). */
     listFormFields(formId: string): Promise<{
         data: Array<{
             name: string;
@@ -820,7 +1127,8 @@ interface PipelineSuggestion {
 }
 /**
  * Stage Checklist Pipelines API - workflow pipelines with evidence + scripts.
- * Requires API key (server-side).
+ * 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/pipelines
@@ -963,7 +1271,9 @@ interface PaginationMeta$2 {
     has_next: boolean;
 }
 /**
- * Quotes API - quote-to-cash lifecycle. Requires API key (server-side).
+ * Quotes API - quote-to-cash lifecycle. 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/quotes
@@ -1116,7 +1426,9 @@ interface InboxSendResult {
 }
 /**
  * Inbox API — read + reply to multi-channel inbox threads (email, SMS, LinkedIn/HeyReach).
- * Requires API key (server-side).
+ * 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
@@ -1323,7 +1635,8 @@ interface SetFieldValueParams {
 }
 /**
  * Fields API - manage custom fields (columns) on contacts and companies.
- * Requires API key (server-side).
+ * 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
@@ -1717,8 +2030,11 @@ declare const createContactsClient: (apiKey: string, apiUrl?: string) => {
     }>;
     /** Get a single contact by ID. */
     get(contactId: number): Promise<Contact>;
-    /** Create a new contact. */
-    create(contact: ContactCreateParams): 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(contact: ContactCreateParams, idempotencyKey?: string): Promise<Contact>;
     /** Update a contact (partial). */
     update(contactId: number, fields: ContactUpdateParams): Promise<{
         updated: number;
@@ -1735,18 +2051,76 @@ declare const createContactsClient: (apiKey: string, apiUrl?: string) => {
     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";
-type WebhookCallback = (data: Record<string, unknown>) => void;
 /**
- * Webhooks - listen for graph8 events. Requires API key (server-side).
+ * Known graph8 webhook event types.
+ *
+ * Source of truth is the backend ``WEBHOOK_EVENTS`` catalog
+ * (campaign_builder/services/webhook_service.py). Keep in sync when the backend
+ * adds events. ``WebhookEvent`` also accepts any string so a newly-added
+ * backend event never breaks a client that hasn't upgraded.
+ */
+declare const KNOWN_WEBHOOK_EVENTS: readonly ["campaign.created", "campaign.updated", "campaign.deleted", "campaign.launched", "campaign.paused", "campaign.completed", "campaign.status_changed", "campaign.content_ready", "document.generated", "document.failed", "intelligence.completed", "intelligence.failed", "company.enriched", "company_intelligence.completed", "audience.ready", "audience.failed", "sequence.deployed", "sequence.started", "sequence.paused", "sequence.completed", "engagement.email_sent", "engagement.email_replied", "engagement.email_bounced", "engagement.email_skipped", "engagement.call_dispatched", "engagement.sms_sent", "engagement.sms_replied", "engagement.whatsapp_sent", "engagement.linkedin_connection_sent", "engagement.linkedin_message_sent", "engagement.linkedin_inmail_sent", "engagement.linkedin_reply_received", "engagement.linkedin_connection_accepted", "meeting.booked", "meeting.cancelled", "meeting.rescheduled"];
+type WebhookEvent = (typeof KNOWN_WEBHOOK_EVENTS)[number] | (string & {});
+/** The decoded body graph8 delivers to a webhook endpoint. */
+interface WebhookEventPayload {
+    event: WebhookEvent;
+    timestamp: string;
+    data: Record<string, unknown>;
+    org_id: string;
+    /** Stable per-delivery id (present once the backend adds it; for consumer dedup). */
+    id?: string;
+}
+interface ConstructEventOptions {
+    /**
+     * Reject events whose ``X-Studio-Timestamp`` is older (or newer) than this
+     * many seconds — replay protection. Disabled when 0/undefined.
+     */
+    toleranceSeconds?: number;
+}
+/** Thrown by {@link constructEvent} when a webhook cannot be verified. */
+declare class WebhookSignatureError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify the HMAC-SHA256 signature of an incoming graph8 webhook and return the
+ * parsed event. Server-side only (needs the per-endpoint signing secret).
+ *
+ * Mirrors the backend signing scheme exactly: the signature is
+ * ``HMAC_SHA256(secret, `${timestamp}.${rawBody}`)`` hex-encoded, delivered in
+ * the ``X-Studio-Signature`` header alongside the unix ``X-Studio-Timestamp``.
  *
- * For client-side real-time events, use g8.visitors.onIntent() or g8.chat.on() instead.
+ * @param payload    The RAW request body string (verify before JSON.parse — re-serializing changes bytes).
+ * @param signature  The ``X-Studio-Signature`` header (an optional ``sha256=`` prefix is tolerated).
+ * @param timestamp  The ``X-Studio-Timestamp`` header (unix seconds).
+ * @param secret     The endpoint's signing secret.
+ * @throws {WebhookSignatureError} on a missing/invalid signature, stale timestamp, or bad JSON.
+ *
+ * @example
+ *   app.post("/webhooks/graph8", (req, res) => {
+ *     const event = g8.webhooks.constructEvent(
+ *       req.rawBody,
+ *       req.header("X-Studio-Signature"),
+ *       req.header("X-Studio-Timestamp"),
+ *       process.env.G8_WEBHOOK_SECRET,
+ *       { toleranceSeconds: 300 },
+ *     );
+ *     if (event.event === "meeting.booked") { ... }
+ *     res.sendStatus(200);
+ *   });
+ */
+declare function constructEvent(payload: string, signature: string, timestamp: string | number, secret: string, opts?: ConstructEventOptions): WebhookEventPayload;
+/**
+ * Webhooks client (server-side). graph8 webhooks are PUSH — graph8 POSTs to your
+ * endpoint; you verify each delivery with {@link constructEvent}. (The previous
+ * polling implementation hit a feed endpoint that never existed and is removed.)
  */
-declare const createWebhooksClient: (apiKey: string, apiUrl?: string) => {
-    /** Register a listener for a webhook event. Starts polling automatically. */
-    on(event: WebhookEvent, callback: WebhookCallback): void;
-    /** Stop all webhook polling. */
-    stop(): void;
+declare const createWebhooksClient: (_apiKey: string, apiUrl?: string) => {
+    /** Base URL the webhook subscription API lives under. */
+    baseUrl: string;
+    /** Known event types (for autocomplete / validation). */
+    knownEvents: readonly ["campaign.created", "campaign.updated", "campaign.deleted", "campaign.launched", "campaign.paused", "campaign.completed", "campaign.status_changed", "campaign.content_ready", "document.generated", "document.failed", "intelligence.completed", "intelligence.failed", "company.enriched", "company_intelligence.completed", "audience.ready", "audience.failed", "sequence.deployed", "sequence.started", "sequence.paused", "sequence.completed", "engagement.email_sent", "engagement.email_replied", "engagement.email_bounced", "engagement.email_skipped", "engagement.call_dispatched", "engagement.sms_sent", "engagement.sms_replied", "engagement.whatsapp_sent", "engagement.linkedin_connection_sent", "engagement.linkedin_message_sent", "engagement.linkedin_inmail_sent", "engagement.linkedin_reply_received", "engagement.linkedin_connection_accepted", "meeting.booked", "meeting.cancelled", "meeting.rescheduled"];
+    /** Verify an incoming webhook's HMAC signature and return the parsed event. */
+    constructEvent(payload: string, signature: string, timestamp: string | number, secret: string, opts?: ConstructEventOptions): WebhookEventPayload;
 };
 
 interface LandingPage {
@@ -1757,7 +2131,9 @@ interface LandingPage {
     published_url: string | null;
 }
 /**
- * Landing pages - clone, create, publish. Requires API key (server-side).
+ * Landing pages - clone, create, publish. Requires API key (server-side). On the
+ * hardened HTTP core: throws a typed `G8Error` on failure and retries transient
+ * errors.
  */
 declare const createPagesClient: (apiKey: string, apiUrl?: string) => {
     /** Clone a landing page from any URL. */
@@ -2115,6 +2491,12 @@ interface AnalyticsOverview {
 }
 /**
  * Analytics - dashboard data and metrics. Requires API key (server-side).
+ *
+ * On the hardened HTTP core: throws a typed `G8Error` on failure and retries
+ * transient errors. Note the deliberate behavior change vs the preview client —
+ * a non-2xx response now **throws** instead of silently returning an all-zeros
+ * overview, so callers can distinguish genuinely-zero activity from an auth/5xx
+ * failure.
  */
 declare const createAnalyticsClient: (apiKey: string, apiUrl?: string) => {
     overview(config?: {
@@ -2147,7 +2529,9 @@ interface Integration {
     connected_at: string | null;
 }
 /**
- * Integrations - connect CRM platforms, trigger syncs. Requires API key (server-side).
+ * Integrations - connect CRM platforms, trigger syncs. Requires API key
+ * (server-side). On the hardened HTTP core: throws a typed `G8Error` on failure
+ * and retries transient errors.
  */
 declare const createIntegrationsClient: (apiKey: string, apiUrl?: string) => {
     list(): Promise<Integration[]>;
@@ -2183,6 +2567,8 @@ interface CampaignStats {
 }
 /**
  * Campaigns - create, manage, launch campaigns. Requires API key (server-side).
+ * On the hardened HTTP core: throws a typed `G8Error` on failure and retries
+ * transient errors.
  */
 declare const createCampaignsClient: (apiKey: string, apiUrl?: string) => {
     list(page?: number, limit?: number): Promise<Campaign[]>;
@@ -2408,22 +2794,40 @@ declare const createSequencesClient: (apiKey: string, apiUrl?: string) => {
         data: SequenceContactItem[];
         pagination?: PaginationMeta;
     }>;
-    /** Add contacts to a sequence (V2 queuing). Live or drafted sequences only. */
-    add(config: AddToSequenceConfig): Promise<SequenceActionResult>;
-    /** Create a new sequence with optional steps + channels. */
-    create(payload: SequenceCreateParams): Promise<SequenceCreateResult>;
+    /**
+     * 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). */
-    run(sequenceId: string): Promise<SequenceActionResult>;
-    /** Pause a live sequence. */
-    pause(sequenceId: string): Promise<SequenceActionResult>;
-    /** Resume a paused sequence. */
-    resume(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. */
@@ -2459,7 +2863,8 @@ interface SearchResults {
 /**
  * Enrichment API - person/company lookup, email verification, prospecting search.
  *
- * Requires API key (server-side only). Credits charged per call.
+ * 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.
  */
 declare const createEnrichClient: (apiKey: string, apiUrl?: string) => {
     /** Look up a person by email, LinkedIn, or name + company. Costs 1 credit. */
@@ -2736,6 +3141,11 @@ declare class G8 {
     /** @internal */ _intent: ReturnType<typeof createIntentClient> | null;
     /** @internal */ _studio: ReturnType<typeof createStudioClient> | null;
     /** @internal */ _meetings: ReturnType<typeof createMeetingsClient> | null;
+    /** @internal */ _audiences: ReturnType<typeof createAudiencesClient> | null;
+    /** @internal */ _search: ReturnType<typeof createSearchClient> | null;
+    /** @internal */ _agency: ReturnType<typeof createAgencyClient> | null;
+    /** @internal */ _marketplace: ReturnType<typeof createMarketplaceClient> | null;
+    /** @internal */ _snippet: ReturnType<typeof createSnippetClient> | 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.
@@ -2796,19 +3206,7 @@ declare class G8 {
             company_domain?: string;
         }): Promise<PersonEnrichment>;
         company(params: {
-            domain
-            /**
-             * graph8 SDK client.
-             *
-             * Handles event tracking, identity, and progressive forms.
-             *
-             * Usage:
-             *   import { g8 } from '@graph8/js';
-             *   g8.init({ writeKey: 'your_write_key' });
-             *   g8.track('page_view', { page: '/pricing' });
-             *   g8.identify('user@acme.com', { name: 'John', company: 'Acme' });
-             */
-            ?: string;
+            domain?: string;
             name?: string;
         }): Promise<CompanyEnrichment>;
         verifyEmail(email: string): Promise<EmailVerification>;
@@ -2826,14 +3224,14 @@ declare class G8 {
             data: SequenceContactItem[];
             pagination?: PaginationMeta;
         }>;
-        add(config: AddToSequenceConfig): Promise<SequenceActionResult>;
-        create(payload: SequenceCreateParams): Promise<SequenceCreateResult>;
+        add(config: AddToSequenceConfig, idempotencyKey?: string): Promise<SequenceActionResult>;
+        create(payload: SequenceCreateParams, idempotencyKey?: string): Promise<SequenceCreateResult>;
         update(sequenceId: string, fields: SequenceUpdateParams): Promise<SequenceActionResult>;
         updateStep(sequenceId: string, stepId: string, fields: SequenceStepUpdateParams): Promise<SequenceActionResult>;
         delete(sequenceId: string): Promise<SequenceActionResult>;
-        run(sequenceId: string): Promise<SequenceActionResult>;
-        pause(sequenceId: string): Promise<SequenceActionResult>;
-        resume(sequenceId: string): Promise<SequenceActionResult>;
+        run(sequenceId: string, idempotencyKey?: string): Promise<SequenceActionResult>;
+        pause(sequenceId: string, idempotencyKey?: string): Promise<SequenceActionResult>;
+        resume(sequenceId: string, idempotencyKey?: string): Promise<SequenceActionResult>;
         preview(sequenceId: string): Promise<SequencePreview>;
         analytics(sequenceId: string): Promise<SequenceAnalytics>;
     };
@@ -2934,8 +3332,9 @@ declare class G8 {
     };
     /** Webhook event listeners (requires API key). */
     get webhooks(): {
-        on(event: WebhookEvent, callback: (data: Record<string, unknown>) => void): void;
-        stop(): void;
+        baseUrl: string;
+        knownEvents: readonly ["campaign.created", "campaign.updated", "campaign.deleted", "campaign.launched", "campaign.paused", "campaign.completed", "campaign.status_changed", "campaign.content_ready", "document.generated", "document.failed", "intelligence.completed", "intelligence.failed", "company.enriched", "company_intelligence.completed", "audience.ready", "audience.failed", "sequence.deployed", "sequence.started", "sequence.paused", "sequence.completed", "engagement.email_sent", "engagement.email_replied", "engagement.email_bounced", "engagement.email_skipped", "engagement.call_dispatched", "engagement.sms_sent", "engagement.sms_replied", "engagement.whatsapp_sent", "engagement.linkedin_connection_sent", "engagement.linkedin_message_sent", "engagement.linkedin_inmail_sent", "engagement.linkedin_reply_received", "engagement.linkedin_connection_accepted", "meeting.booked", "meeting.cancelled", "meeting.rescheduled"];
+        constructEvent(payload: string, signature: string, timestamp: string | number, secret: string, opts?: ConstructEventOptions): WebhookEventPayload;
     };
     /** Contacts CRUD (requires API key). */
     get contacts(): {
@@ -2944,7 +3343,7 @@ declare class G8 {
             total: number;
         }>;
         get(contactId: number): Promise<Contact>;
-        create(contact: ContactCreateParams): Promise<Contact>;
+        create(contact: ContactCreateParams, idempotencyKey?: string): Promise<Contact>;
         update(contactId: number, fields: ContactUpdateParams): Promise<{
             updated: number;
         }>;
@@ -3346,7 +3745,7 @@ declare class G8 {
         }>;
         keywordContacts(keywordId: string, params?: {
             limit?: number;
-            date_from? /** @internal */: string;
+            date_from?: string;
             date_to?: string;
         }): Promise<{
             data: IntentContact[];
@@ -3409,7 +3808,7 @@ declare class G8 {
         }>;
         personas(params?: {
             status?: string;
-            limit?: number;
+            limit? /** @internal */: number;
         }): Promise<{
             data: Persona[];
         }>;
@@ -3439,6 +3838,63 @@ declare class G8 {
         }>;
         get(meetingId: string): Promise<MeetingDetail>;
     };
+    /** Audiences — sync audience lists to ad platforms (Meta, LinkedIn, Google, X) (requires API key). */
+    get audiences(): {
+        list(): Promise<{
+            data: AudienceSync[];
+        }>;
+        create(params: AudienceSyncCreateParams): Promise<AudienceSync>;
+        get(configId: number): Promise<AudienceSync>;
+        update(configId: number, fields: AudienceSyncUpdateParams): Promise<AudienceSync>;
+        delete(configId: number): Promise<{
+            data: Record<string, unknown>;
+        }>;
+        trigger(configId: number): Promise<{
+            data: Record<string, unknown>;
+        }>;
+        runs(configId: number): Promise<{
+            data: AudienceSyncRun[];
+        }>;
+        errors(configId: number): Promise<{
+            data: AudienceSyncError[];
+        }>;
+    };
+    /** Search — prospect open-data contacts + companies by filter, optionally save to a list (requires API key). */
+    get search(): {
+        contacts(params?: SearchParams): Promise<{
+            data: SearchContactItem[];
+        }>;
+        companies(params?: SearchParams): Promise<{
+            data: SearchCompanyItem[];
+        }>;
+        saveContacts(params: SearchSaveParams): Promise<SearchSaveResult>;
+        saveCompanies(params: SearchSaveParams): Promise<SearchSaveResult>;
+    };
+    /** Agency — for agency keys: discover the agency credential + the client orgs it may target (requires API key). */
+    get agency(): {
+        me(): Promise<AgencyInfo>;
+        clients(): Promise<{
+            data: AgencyClient[];
+        }>;
+    };
+    /** Marketplace — for SDR/AE talent: profile, hire offers (accept/reject), active hirings (requires API key). */
+    get marketplace(): {
+        profile(): Promise<MarketplaceProfile>;
+        offers(): Promise<{
+            offers: MarketplaceOffer[];
+            count: number;
+        }>;
+        acceptOffer(hiringId: string): Promise<Record<string, unknown>>;
+        rejectOffer(hiringId: string): Promise<Record<string, unknown>>;
+        hirings(): Promise<{
+            hirings: MarketplaceHiring[];
+            count: number;
+        }>;
+    };
+    /** Snippet — fetch your org's tracking snippet (write key + React/script-tag embeds + config) for embedding (requires API key). */
+    get snippet(): {
+        get(): Promise<Snippet>;
+    };
     /** Whether the SDK has been initialized. */
     get initialized(): boolean;
     /** @internal */
@@ -3449,4 +3905,88 @@ 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 CallGradingResult, 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 DialerAgentSummary, type DialerAgentsListParams, type DialerAgentsListResult, type DialerNumberInfo, type DialerNumbersListResult, type DialerReportFilters, type DialerReportMetric, type DialerSessionCreateParams, type DialerSessionCreateResult, type DialerSessionResumeResult, type DialerSessionStatus, type DialerSessionStatusUpdateResult, type DialerSessionSummary, type DialerSessionsListParams, type DialerSessionsListResult, type DialerStatsParams, type DialerStatsResult, type EmailVerification, type EnrichLookupResult, type EvidenceKey, type Field, type FieldCreateParams, type FieldDeleteParams, type G8Config, type G8PrivacyConfig, type GlobalContextDocument, type ICP, type IdentifyProperties, type InboxAssignResult, type InboxAssignee, type InboxChannel, type InboxContact, type InboxDraft, type InboxListParams, type InboxMessage, type InboxSendParams, type InboxSendResult, type InboxTag, type InboxTagResult, type InboxThread, type Integration, type IntelligenceData, type IntentCompany, type IntentContact, type IntentKeyword, type IntentPage, type IntentSignals, type IntentStats, type IntentVisitor, type LandingPage, type ListContact, type MeetingAnalysis, type MeetingAttendee, type MeetingDetail, type MeetingListParams, type MeetingSummary, type MeetingTranscriptLine, type MissedCallback, type MissedCallbacksResult, type NodeTypeSchema, type Note, type PaginationMeta$1 as PaginationMeta, type PersonEnrichment, type Persona, type Pipeline, type PipelineStage, type PipelineSuggestion, type QuotableProduct, type QuoteCreateParams, type QuoteDetail, type QuoteLineItem, type QuoteListParams, type QuoteSendParams, type QuoteSettings, type QuoteStatus, type QuoteSummary, type QuoteUpdateParams, type ResearchReport, type SearchFilter, type SearchResults, type Sequence, type SequenceActionResult, type SequenceAnalytics, type SequenceChannelConfig, type SequenceContactItem, type SequenceContactsParams, type SequenceCreateParams, type SequenceCreateResult, type SequenceDetail, type SequenceKind, type SequenceListItem, type SequenceListParams, type SequencePreview, type SequencePreviewChannel, type SequencePreviewStep, type SequenceStepConfig, type SequenceStepInputType, type SequenceStepType, type SequenceStepUpdateParams, type SequenceUpdateParams, type SetFieldValueParams, type Skill, type SkillCreateAPIParams, type SkillCreateLLMParams, type SkillInputField, type SkillListParams, type SkillTemplate, type SkillType, type SkillUpdateAPIParams, type SkillUpdateLLMParams, type StageCreateParams, type StagePipeline, type StagePipelineCreateParams, type StagePipelineStage, type StagePipelineUpdateParams, type StageUpdateParams, type Task, type TaskCreateParams, type TaskListParams, type TaskUpdateParams, type TimeSlot, type TrackProperties, type VisitorCompany, type VisitorScore, type VoicePagination, type VoiceSession, type WebhookEvent, type Workflow, type WorkflowConfig, type WorkflowConnection, type WorkflowCreateParams, type WorkflowExecution, type WorkflowListParams, type WorkflowNode, type WorkflowUpdateParams, g8 };
+/**
+ * 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;
+ *   - `Idempotency-Key` support for safe POST retries (pairs with the backend
+ *     idempotency added in A6);
+ *   - 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.
+ */
+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. */
+declare function isRetryableStatus(status: number): 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.
+ */
+declare function parseRetryAfter(header: string | null | undefined, nowMs?: number): number | null;
+/** Exponential backoff with full jitter, capped at 10s. */
+declare function backoffDelayMs(attempt: number, baseMs?: number, rand?: () => number): number;
+interface RequestOptions {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    /** Sent as the `Idempotency-Key` header (safe POST retries; see A6). */
+    idempotencyKey?: string;
+    /** Max retry attempts on 429/5xx/network (default 2 -> up to 3 tries). */
+    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.
+ */
+declare function request<T = unknown>(baseUrl: string, path: string, apiKey: string, opts?: RequestOptions): Promise<T>;
+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.
+ */
+declare function paginate<T>(fetchPage: (cursor?: string) => Promise<PaginatedResponse<T>>): AsyncGenerator<T, void, unknown>;
+
+export { type AddToSequenceConfig, type AgencyClient, type AgencyInfo, type AnalyticsOverview, type AudienceSync, type AudienceSyncCreateParams, type AudienceSyncError, type AudienceSyncMode, type AudienceSyncPlatform, type AudienceSyncRun, type AudienceSyncUpdateParams, type Booking, type BookingRequest, type CalendarConfig, type CallAnalysis, type CallGradingResult, type Campaign, type CampaignCreateConfig, type CampaignStats, type ChatConfig, type Company, type CompanyColumn, type CompanyColumnCreateParams, type CompanyContact, type CompanyEnrichment, type CompanyListParams, type CompanyUpdateParams, type ConstructEventOptions, 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 DialerAgentSummary, type DialerAgentsListParams, type DialerAgentsListResult, type DialerNumberInfo, type DialerNumbersListResult, type DialerReportFilters, type DialerReportMetric, type DialerSessionCreateParams, type DialerSessionCreateResult, type DialerSessionResumeResult, type DialerSessionStatus, type DialerSessionStatusUpdateResult, type DialerSessionSummary, type DialerSessionsListParams, type DialerSessionsListResult, type DialerStatsParams, type DialerStatsResult, type EmailVerification, type EnrichLookupResult, type EvidenceKey, type Field, type FieldCreateParams, type FieldDeleteParams, type G8Config, G8Error, type G8PrivacyConfig, type GlobalContextDocument, type ICP, type IdentifyProperties, type InboxAssignResult, type InboxAssignee, type InboxChannel, type InboxContact, type InboxDraft, type InboxListParams, type InboxMessage, type InboxSendParams, type InboxSendResult, type InboxTag, type InboxTagResult, type InboxThread, type Integration, type IntelligenceData, type IntentCompany, type IntentContact, type IntentKeyword, type IntentPage, type IntentSignals, type IntentStats, type IntentVisitor, KNOWN_WEBHOOK_EVENTS, type LandingPage, type ListContact, type MarketplaceHiring, type MarketplaceOffer, type MarketplaceProfile, type MeetingAnalysis, type MeetingAttendee, type MeetingDetail, type MeetingListParams, type MeetingSummary, type MeetingTranscriptLine, type MissedCallback, type MissedCallbacksResult, type NodeTypeSchema, type Note, type PaginatedResponse, type PaginationMeta$1 as PaginationMeta, type PersonEnrichment, type Persona, type Pipeline, type PipelineStage, type PipelineSuggestion, type QuotableProduct, type QuoteCreateParams, type QuoteDetail, type QuoteLineItem, type QuoteListParams, type QuoteSendParams, type QuoteSettings, type QuoteStatus, type QuoteSummary, type QuoteUpdateParams, type RequestOptions, type ResearchReport, type SearchCompanyItem, type SearchCondition, type SearchContactItem, type SearchFilter, type SearchOperator, type SearchParams, type SearchResults, type SearchSaveParams, type SearchSaveResult, type Sequence, type SequenceActionResult, type SequenceAnalytics, type SequenceChannelConfig, type SequenceContactItem, type SequenceContactsParams, type SequenceCreateParams, type SequenceCreateResult, type SequenceDetail, type SequenceKind, type SequenceListItem, type SequenceListParams, type SequencePreview, type SequencePreviewChannel, type SequencePreviewStep, type SequenceStepConfig, type SequenceStepInputType, type SequenceStepType, type SequenceStepUpdateParams, type SequenceUpdateParams, type SetFieldValueParams, type Skill, type SkillCreateAPIParams, type SkillCreateLLMParams, type SkillInputField, type SkillListParams, type SkillTemplate, type SkillType, type SkillUpdateAPIParams, type SkillUpdateLLMParams, type Snippet, type StageCreateParams, type StagePipeline, type StagePipelineCreateParams, type StagePipelineStage, type StagePipelineUpdateParams, type StageUpdateParams, type Task, type TaskCreateParams, type TaskListParams, type TaskUpdateParams, type TimeSlot, type TrackProperties, type VisitorCompany, type VisitorScore, type VoicePagination, type VoiceSession, type WebhookEvent, type WebhookEventPayload, WebhookSignatureError, type Workflow, type WorkflowConfig, type WorkflowConnection, type WorkflowCreateParams, type WorkflowExecution, type WorkflowListParams, type WorkflowNode, type WorkflowUpdateParams, backoffDelayMs, constructEvent, g8, isRetryableStatus, paginate, parseRetryAfter, request };