@graph8/sdk 0.12.0 → 0.12.2

package/dist/index.d.mts

@@ -578,6 +578,29 @@ interface IntentCompany {
     visit_count: number;
     last_seen: string | null;
 }
+/** One company row from `intent.urlCompanies()`. Richer than {@link IntentCompany},
+ * which describes the keyword-companies surface. */
+interface IntentUrlCompany {
+    company_id: number | null;
+    name: string | null;
+    domain: string | null;
+    industry: string | null;
+    employee_count: number | null;
+    logo_url: string | null;
+    audience: string;
+    visit_count: number;
+    contacts_seen: number;
+    last_seen: string | null;
+}
+/** Response of `intent.urlCompanies()`. This endpoint returns a bare aggregate,
+ * not the `{ data }` envelope the rest of the Developer API uses. */
+interface IntentUrlCompaniesResponse {
+    url: string;
+    total_companies: number;
+    b2b_count: number;
+    b2c_count: number;
+    companies: IntentUrlCompany[];
+}
 interface IntentContact {
     contact_id: number | null;
     email: string | null;
@@ -612,7 +635,7 @@ interface IntentStats {
  *   POST   /api/v1/intent/pages/visitors
  *   POST   /api/v1/intent/pages/contacts
  *   POST   /api/v1/intent/pages/visitor-counts
- *   POST   /intent-search/url-companies          (note: bare host, no /api/v1 prefix)
+ *   POST   /api/v1/intent/url-companies
  */
 declare const createIntentClient: (apiKey: string, apiUrl?: string) => {
     /** Org-level intent stats (totals over the last 30 days). */
@@ -695,16 +718,24 @@ declare const createIntentClient: (apiKey: string, apiUrl?: string) => {
     /**
      * Find companies whose users visited a specific URL (intent search).
      *
-     * Note: this endpoint lives at the bare host (no `/api/v1` prefix), unlike the rest
-     * of the intent surface — we call it directly here instead of through the shared `post()` helper.
+     * Previously posted to the bare-host `/intent-search/url-companies`, bypassing
+     * the shared `post()` helper. That route is JWT-only, so this method could
+     * never actually work with an API key. It now goes through
+     * `/api/v1/intent/url-companies` like the rest of the intent surface (g8 issue
+     * #16536).
+     *
+     * Returns a bare aggregate, NOT the `{ data }` envelope — the previous
+     * `{ data: IntentCompany[] }` signature never matched what the API sends.
+     *
+     * `date_from` / `date_to` are accepted for backwards compatibility but have
+     * never been read by this endpoint; use `days` to set the lookback window.
      */
     urlCompanies(url: string, params?: {
         limit?: number;
+        days?: number;
         date_from?: string;
         date_to?: string;
-    }): Promise<{
-        data: IntentCompany[];
-    }>;
+    }): Promise<IntentUrlCompaniesResponse>;
 };
 
 type SkillType = "llm" | "api";
@@ -1553,14 +1584,28 @@ interface DealCreateParams {
      */
     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. Defaults to first stage of default pipeline if omitted. */
+    /**
+     * 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. Defaults to org's default pipeline if omitted. */
+    /** Pipeline ID. Must exist (HTTP 422 otherwise). Defaults to org's default pipeline if omitted. */
     pipeline_id?: string;
-    /** ISO 8601 close date. */
+    /**
+     * 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.
@@ -1573,10 +1618,28 @@ interface DealUpdateParams {
     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. */
-    close_date?: string;
-    /** Reassign the deal owner (user id or email). Pass null to clear. */
+    /**
+     * 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 (user id or email). Pass null to clear, except on
+     * a deal sitting in a closed stage (HTTP 400, marker
+     * `owner_required_for_closed_stage`).
+     */
     owner_id?: string | null;
     /**
      * mashup_contact_ids to link. Must belong to the deal's company (if the deal
@@ -3717,7 +3780,7 @@ declare class G8 {
             data: IntentCompany[];
         }>;
         keywordContacts(keywordId: string, params?: {
-            limit? /** @internal */: number;
+            limit?: number;
             date_from?: string;
             date_to?: string;
         }): Promise<{
@@ -3758,11 +3821,10 @@ declare class G8 {
         }>;
         urlCompanies(url: string, params?: {
             limit?: number;
+            days?: number;
             date_from?: string;
             date_to?: string;
-        }): Promise<{
-            data: IntentCompany[];
-        }>;
+        }): Promise<IntentUrlCompaniesResponse>;
     };
     /** Studio context — ICPs, personas, brand briefs, intelligence, AI research reports (requires API key). */
     get studio(): {

package/dist/index.d.ts

@@ -578,6 +578,29 @@ interface IntentCompany {
     visit_count: number;
     last_seen: string | null;
 }
+/** One company row from `intent.urlCompanies()`. Richer than {@link IntentCompany},
+ * which describes the keyword-companies surface. */
+interface IntentUrlCompany {
+    company_id: number | null;
+    name: string | null;
+    domain: string | null;
+    industry: string | null;
+    employee_count: number | null;
+    logo_url: string | null;
+    audience: string;
+    visit_count: number;
+    contacts_seen: number;
+    last_seen: string | null;
+}
+/** Response of `intent.urlCompanies()`. This endpoint returns a bare aggregate,
+ * not the `{ data }` envelope the rest of the Developer API uses. */
+interface IntentUrlCompaniesResponse {
+    url: string;
+    total_companies: number;
+    b2b_count: number;
+    b2c_count: number;
+    companies: IntentUrlCompany[];
+}
 interface IntentContact {
     contact_id: number | null;
     email: string | null;
@@ -612,7 +635,7 @@ interface IntentStats {
  *   POST   /api/v1/intent/pages/visitors
  *   POST   /api/v1/intent/pages/contacts
  *   POST   /api/v1/intent/pages/visitor-counts
- *   POST   /intent-search/url-companies          (note: bare host, no /api/v1 prefix)
+ *   POST   /api/v1/intent/url-companies
  */
 declare const createIntentClient: (apiKey: string, apiUrl?: string) => {
     /** Org-level intent stats (totals over the last 30 days). */
@@ -695,16 +718,24 @@ declare const createIntentClient: (apiKey: string, apiUrl?: string) => {
     /**
      * Find companies whose users visited a specific URL (intent search).
      *
-     * Note: this endpoint lives at the bare host (no `/api/v1` prefix), unlike the rest
-     * of the intent surface — we call it directly here instead of through the shared `post()` helper.
+     * Previously posted to the bare-host `/intent-search/url-companies`, bypassing
+     * the shared `post()` helper. That route is JWT-only, so this method could
+     * never actually work with an API key. It now goes through
+     * `/api/v1/intent/url-companies` like the rest of the intent surface (g8 issue
+     * #16536).
+     *
+     * Returns a bare aggregate, NOT the `{ data }` envelope — the previous
+     * `{ data: IntentCompany[] }` signature never matched what the API sends.
+     *
+     * `date_from` / `date_to` are accepted for backwards compatibility but have
+     * never been read by this endpoint; use `days` to set the lookback window.
      */
     urlCompanies(url: string, params?: {
         limit?: number;
+        days?: number;
         date_from?: string;
         date_to?: string;
-    }): Promise<{
-        data: IntentCompany[];
-    }>;
+    }): Promise<IntentUrlCompaniesResponse>;
 };
 
 type SkillType = "llm" | "api";
@@ -1553,14 +1584,28 @@ interface DealCreateParams {
      */
     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. Defaults to first stage of default pipeline if omitted. */
+    /**
+     * 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. Defaults to org's default pipeline if omitted. */
+    /** Pipeline ID. Must exist (HTTP 422 otherwise). Defaults to org's default pipeline if omitted. */
     pipeline_id?: string;
-    /** ISO 8601 close date. */
+    /**
+     * 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.
@@ -1573,10 +1618,28 @@ interface DealUpdateParams {
     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. */
-    close_date?: string;
-    /** Reassign the deal owner (user id or email). Pass null to clear. */
+    /**
+     * 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 (user id or email). Pass null to clear, except on
+     * a deal sitting in a closed stage (HTTP 400, marker
+     * `owner_required_for_closed_stage`).
+     */
     owner_id?: string | null;
     /**
      * mashup_contact_ids to link. Must belong to the deal's company (if the deal
@@ -3717,7 +3780,7 @@ declare class G8 {
             data: IntentCompany[];
         }>;
         keywordContacts(keywordId: string, params?: {
-            limit? /** @internal */: number;
+            limit?: number;
             date_from?: string;
             date_to?: string;
         }): Promise<{
@@ -3758,11 +3821,10 @@ declare class G8 {
         }>;
         urlCompanies(url: string, params?: {
             limit?: number;
+            days?: number;
             date_from?: string;
             date_to?: string;
-        }): Promise<{
-            data: IntentCompany[];
-        }>;
+        }): Promise<IntentUrlCompaniesResponse>;
     };
     /** Studio context — ICPs, personas, brand briefs, intelligence, AI research reports (requires API key). */
     get studio(): {

package/dist/index.js

@@ -1745,14 +1745,20 @@ var createIntentClient = (apiKey, apiUrl) => {
     /**
      * Find companies whose users visited a specific URL (intent search).
      *
-     * Note: this endpoint lives at the bare host (no `/api/v1` prefix), unlike the rest
-     * of the intent surface — we call it directly here instead of through the shared `post()` helper.
+     * Previously posted to the bare-host `/intent-search/url-companies`, bypassing
+     * the shared `post()` helper. That route is JWT-only, so this method could
+     * never actually work with an API key. It now goes through
+     * `/api/v1/intent/url-companies` like the rest of the intent surface (g8 issue
+     * #16536).
+     *
+     * Returns a bare aggregate, NOT the `{ data }` envelope — the previous
+     * `{ data: IntentCompany[] }` signature never matched what the API sends.
+     *
+     * `date_from` / `date_to` are accepted for backwards compatibility but have
+     * never been read by this endpoint; use `days` to set the lookback window.
      */
     async urlCompanies(url, params = {}) {
-      return request(baseUrl, "/intent-search/url-companies", apiKey, {
-        method: "POST",
-        body: { url, ...params }
-      });
+      return post("/intent/url-companies", { url, ...params });
     }
   };
 };