@graph8/sdk 0.11.0 → 0.12.2

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(): {
@@ -4016,4 +4078,229 @@ interface PaginatedResponse<T> {
  */
 declare function paginate<T>(fetchPage: (cursor?: string) => Promise<PaginatedResponse<T>>): AsyncGenerator<T, void, unknown>;
 
-export { type AddToSequenceConfig, type AgencyClient, type AgencyInfo, type AudienceSync, type AudienceSyncCreateParams, type AudienceSyncError, type AudienceSyncMode, type AudienceSyncPlatform, type AudienceSyncRun, type AudienceSyncUpdateParams, type Booking, type BookingRequest, type CalendarConfig, type CallGradingResult, type Campaign, type CampaignCreateConfig, type CampaignLaunchExecution, type CampaignLaunchResult, 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 IntelligenceData, type IntentCompany, type IntentContact, type IntentKeyword, type IntentPage, type IntentSignals, type IntentStats, type IntentVisitor, KNOWN_WEBHOOK_EVENTS, 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 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 };
+/**
+ * App-platform token exchange + refresh core (M6-9).
+ *
+ * The hosted-app clients never carry a permanent org API key. Instead they mint
+ * SHORT-LIVED app tokens by EXCHANGING a longer-lived credential, and refresh
+ * them on/near expiry:
+ *
+ *   - browser apps exchange the caller's PropelAuth login at
+ *     `POST /api/v1/app-sessions/exchange` (identity is derived server-side from
+ *     the validated principal — the body only names the target app + scopes);
+ *   - hosted backends exchange service client-credentials at
+ *     `POST /api/v1/service-token`.
+ *
+ * Both endpoints answer with the reused `ApiResponse` envelope wrapping a
+ * `TokenResponse` (see developer_api/app_platform/app_tokens/dtos.py). This
+ * module owns:
+ *
+ *   - `AppTokenResponse` — the minted-token payload shape (frozen wire contract);
+ *   - `createTokenManager` — caches a token, refreshes it on/near expiry, and
+ *     de-dupes concurrent refreshes into one in-flight exchange;
+ *   - `createAppRequester` — binds the managed token onto the hardened
+ *     `request()` core (typed `G8Error`, retries, idempotency, pagination),
+ *     attaching `Authorization: Bearer <app-token>` (plus any static header such
+ *     as a service client's `X-Target-Org-Id`) and refreshing once on a 401.
+ *
+ * The backend app-token API is INERT/unmounted today (behind a deny-by-default
+ * flag), so these paths are exercised against mocked HTTP, never a live server.
+ */
+declare const DEFAULT_APP_API = "https://be.graph8.com";
+/** The minted app token + the non-secret metadata a client reads back.
+ *  Mirrors `TokenResponse` in developer_api/app_platform/app_tokens/dtos.py. */
+interface AppTokenResponse {
+    /** The signed app JWT (attach as `Authorization: Bearer <access_token>`). */
+    access_token: string;
+    /** Always "Bearer". */
+    token_type: string;
+    /** Lifetime in seconds from issuance. */
+    expires_in: number;
+    /** The distinct-per-app, per-environment audience. */
+    audience: string;
+    /** App the token is bound to (dapp_-prefixed). */
+    app_id: string;
+    /** Signing key id (matches a JWKS entry). */
+    kid: string;
+}
+/** Per-request options accepted by an {@link AppRequest}. A subset of the
+ *  hardened core's `RequestOptions` — auth (the app token) and the injected
+ *  fetch/sleep seams are bound by the requester, not passed per call. */
+interface AppRequestOptions {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    /** Sent as `Idempotency-Key` for safe POST/PATCH retries. */
+    idempotencyKey?: string;
+    /** Max retry attempts on 429/5xx/network (default 2). */
+    maxRetries?: number;
+    /** Base backoff in ms (default 200). */
+    retryBaseMs?: number;
+    signal?: AbortSignal;
+}
+/** A token-bound request function: same ergonomics as the raw `request()` core
+ *  minus the credential, which the token manager supplies. */
+type AppRequest = <T = unknown>(path: string, opts?: AppRequestOptions) => Promise<T>;
+/** Caches + refreshes one app token. */
+interface TokenManager {
+    /** Return a valid token, refreshing on/near expiry. `force` refreshes now. */
+    getToken(force?: boolean): Promise<string>;
+    /** Current token expiry as an epoch-ms timestamp (0 before the first mint). */
+    expiresAt(): number;
+}
+/**
+ * Build a token manager over a `refresh` exchange.
+ *
+ * Freshness rule: a cached token is reused until it is within `refreshSkewMs`
+ * of expiry, then a refresh is triggered. Concurrent callers during a refresh
+ * share ONE in-flight exchange (no stampede). `now` is injectable for tests.
+ */
+declare function createTokenManager(args: {
+    refresh: () => Promise<AppTokenResponse>;
+    now?: () => number;
+    refreshSkewMs?: number;
+}): TokenManager;
+/**
+ * Bind a {@link TokenManager} onto the hardened `request()` core.
+ *
+ * Every call fetches the current token, attaches `Authorization: Bearer …`
+ * (plus any `extraHeaders`, e.g. a service client's `X-Target-Org-Id`), and
+ * reuses all of the core's typed errors / retries / idempotency. On a 401 —
+ * a token revoked or gone stale mid-window — it force-refreshes ONCE and retries.
+ */
+declare function createAppRequester(args: {
+    baseUrl: string;
+    tokens: TokenManager;
+    extraHeaders?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): AppRequest;
+/**
+ * Exchange the caller's PropelAuth token for a short-lived BROWSER app token.
+ * `POST /api/v1/app-sessions/exchange` (body = target app + scopes only;
+ * identity/role/tenant are derived server-side from the validated principal).
+ */
+declare function exchangeBrowserToken(args: {
+    baseUrl: string;
+    appId: string;
+    scopes?: string[];
+    getPropelAuthToken: () => string | Promise<string>;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): Promise<AppTokenResponse>;
+/**
+ * Exchange service client-credentials for a SERVICE app token.
+ * `POST /api/v1/service-token` — credentials travel in the body; this endpoint
+ * has no bearer auth, so no `Authorization` is sent on the exchange itself.
+ */
+declare function exchangeServiceToken(args: {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    scopes?: string[];
+    ttlSeconds?: number;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): Promise<AppTokenResponse>;
+
+/**
+ * Hosted app-platform clients (M6-9).
+ *
+ * Two entry points, both additive to `@graph8/sdk` and independent of the
+ * `g8` tracking/API-key singleton:
+ *
+ *   - `createGraph8AppClient` — BROWSER client. Exchanges the caller's
+ *     PropelAuth token for a short-lived app token, refreshes it on/near expiry,
+ *     and attaches `Authorization: Bearer <app-token>` to every call. It NEVER
+ *     accepts a permanent org API key for browser init (the whole reason the
+ *     token-exchange exists).
+ *   - `createGraph8ServiceClient` — BACKEND client. Exchanges service
+ *     client-credentials for a service app token and sends `X-Target-Org-Id`
+ *     for the single configured tenant on every call.
+ *
+ * Both expose a token-bound `request()` — the hardened `request()` core with the
+ * minted app token attached — so callers reach Developer API routes with the
+ * app token and reuse the core's typed `G8Error`, retries, idempotency, and
+ * cursor pagination. The typed `apps` (control-plane) and `objects`
+ * (custom-object CRUD) resource modules are DEFERRED until their backend routes
+ * ship and freeze (M6-3 / M6-5); only the auth clients ship here.
+ */
+
+/** Config for {@link createGraph8AppClient} (browser). No API key is accepted. */
+interface Graph8AppClientConfig {
+    /** Target app id (dapp_-prefixed). */
+    appId: string;
+    /** The client org this browser session acts in (informational; the server
+     *  derives the authoritative tenant from the validated PropelAuth principal). */
+    tenantOrgId: string;
+    /** Returns the caller's current PropelAuth token (sync or async). */
+    getPropelAuthToken: () => string | Promise<string>;
+    /** Scopes to embed in the minted app token. */
+    scopes?: string[];
+    /** Backend API URL (default https://be.graph8.com). */
+    apiUrl?: string;
+    /** Refresh this many ms before expiry (default 60_000). */
+    refreshSkewMs?: number;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests; defaults to a real setTimeout sleep. */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Injected for tests; defaults to Date.now. */
+    now?: () => number;
+}
+/** A browser app-platform client. */
+interface Graph8AppClient {
+    readonly appId: string;
+    readonly tenantOrgId: string;
+    /** Token-bound requester: mints/refreshes the app token and attaches
+     *  `Authorization: Bearer <app-token>` to every Developer API call. */
+    readonly request: AppRequest;
+    /** Return the current app token, refreshing on/near expiry (`force` refreshes now). */
+    getAppToken(force?: boolean): Promise<string>;
+}
+/**
+ * Create a BROWSER app-platform client backed by PropelAuth->app-token exchange.
+ * Refuses an org API key / write key — those must never reach a browser.
+ */
+declare function createGraph8AppClient(config: Graph8AppClientConfig): Graph8AppClient;
+/** Config for {@link createGraph8ServiceClient} (backend / server-to-server). */
+interface Graph8ServiceClientConfig {
+    /** Service credential client id. */
+    clientId: string;
+    /** Service credential client secret (checked against the stored hash). */
+    clientSecret: string;
+    /** The single consented client org this backend acts for (sent as X-Target-Org-Id). */
+    tenantOrgId: string;
+    /** Scopes to embed in the minted service token. */
+    scopes?: string[];
+    /** Requested token TTL; the server clamps it into its service band. */
+    ttlSeconds?: number;
+    /** Backend API URL (default https://be.graph8.com). */
+    apiUrl?: string;
+    /** Refresh this many ms before expiry (default 60_000). */
+    refreshSkewMs?: number;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests; defaults to a real setTimeout sleep. */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Injected for tests; defaults to Date.now. */
+    now?: () => number;
+}
+/** A backend service app-platform client. */
+interface Graph8ServiceClient {
+    readonly tenantOrgId: string;
+    /** Token-bound requester: mints/refreshes the service token, attaches it, and
+     *  sends `X-Target-Org-Id` for the one consented tenant on every call. */
+    readonly request: AppRequest;
+    /** Return the current service token, refreshing on/near expiry (`force` refreshes now). */
+    getServiceToken(force?: boolean): Promise<string>;
+}
+/**
+ * Create a BACKEND service client backed by client-credentials->service-token
+ * exchange. Every request carries `X-Target-Org-Id: <tenantOrgId>` for the one
+ * configured consented tenant.
+ */
+declare function createGraph8ServiceClient(config: Graph8ServiceClientConfig): Graph8ServiceClient;
+
+export { type AddToSequenceConfig, type AgencyClient, type AgencyInfo, type AppRequest, type AppRequestOptions, type AppTokenResponse, type AudienceSync, type AudienceSyncCreateParams, type AudienceSyncError, type AudienceSyncMode, type AudienceSyncPlatform, type AudienceSyncRun, type AudienceSyncUpdateParams, type Booking, type BookingRequest, type CalendarConfig, type CallGradingResult, type Campaign, type CampaignCreateConfig, type CampaignLaunchExecution, type CampaignLaunchResult, 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, DEFAULT_APP_API, 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 Graph8AppClient, type Graph8AppClientConfig, type Graph8ServiceClient, type Graph8ServiceClientConfig, 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 IntelligenceData, type IntentCompany, type IntentContact, type IntentKeyword, type IntentPage, type IntentSignals, type IntentStats, type IntentVisitor, KNOWN_WEBHOOK_EVENTS, 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 TokenManager, type TrackProperties, type VisitorCompany, type VisitorScore, type VoicePagination, type WebhookEvent, type WebhookEventPayload, WebhookSignatureError, type Workflow, type WorkflowConfig, type WorkflowConnection, type WorkflowCreateParams, type WorkflowExecution, type WorkflowListParams, type WorkflowNode, type WorkflowUpdateParams, backoffDelayMs, constructEvent, createAppRequester, createGraph8AppClient, createGraph8ServiceClient, createTokenManager, exchangeBrowserToken, exchangeServiceToken, g8, isRetryableStatus, paginate, parseRetryAfter, request };

package/dist/index.js

@@ -20,11 +20,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_APP_API: () => DEFAULT_APP_API,
   G8Error: () => G8Error,
   KNOWN_WEBHOOK_EVENTS: () => KNOWN_WEBHOOK_EVENTS,
   WebhookSignatureError: () => WebhookSignatureError,
   backoffDelayMs: () => backoffDelayMs,
   constructEvent: () => constructEvent,
+  createAppRequester: () => createAppRequester,
+  createGraph8AppClient: () => createGraph8AppClient,
+  createGraph8ServiceClient: () => createGraph8ServiceClient,
+  createTokenManager: () => createTokenManager,
+  exchangeBrowserToken: () => exchangeBrowserToken,
+  exchangeServiceToken: () => exchangeServiceToken,
   g8: () => g8,
   isRetryableStatus: () => isRetryableStatus,
   paginate: () => paginate,
@@ -1738,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 });
     }
   };
 };
@@ -2302,13 +2315,182 @@ var G8 = class {
   }
 };
 var g8 = new G8();
+
+// src/appTokens.ts
+var DEFAULT_APP_API = "https://be.graph8.com";
+function createTokenManager(args) {
+  const now = args.now ?? (() => Date.now());
+  const skewMs = args.refreshSkewMs ?? 6e4;
+  let token = null;
+  let expiresAtMs = 0;
+  let inflight = null;
+  const doRefresh = async () => {
+    const resp = await args.refresh();
+    token = resp.access_token;
+    expiresAtMs = now() + Math.max(0, resp.expires_in) * 1e3;
+    return token;
+  };
+  return {
+    async getToken(force = false) {
+      const stillFresh = !force && token !== null && now() < expiresAtMs - skewMs;
+      if (stillFresh) return token;
+      if (!inflight) {
+        inflight = doRefresh().finally(() => {
+          inflight = null;
+        });
+      }
+      return inflight;
+    },
+    expiresAt() {
+      return expiresAtMs;
+    }
+  };
+}
+function createAppRequester(args) {
+  const { baseUrl, tokens, extraHeaders, fetchImpl, sleepImpl } = args;
+  const appRequest = async (path, opts = {}) => {
+    const headers = { ...extraHeaders ?? {}, ...opts.headers ?? {} };
+    const reqOpts = { ...opts, headers, fetchImpl, sleepImpl };
+    const token = await tokens.getToken();
+    try {
+      return await request(baseUrl, path, token, reqOpts);
+    } catch (err) {
+      if (err instanceof G8Error && err.status === 401) {
+        const fresh = await tokens.getToken(true);
+        return await request(baseUrl, path, fresh, reqOpts);
+      }
+      throw err;
+    }
+  };
+  return appRequest;
+}
+async function exchangeBrowserToken(args) {
+  const propelToken = await Promise.resolve(args.getPropelAuthToken());
+  if (!propelToken) {
+    throw new G8Error({
+      message: "getPropelAuthToken() returned no token \u2014 cannot exchange a browser app session",
+      status: 401,
+      type: "app_token_invalid",
+      code: "app_token_invalid"
+    });
+  }
+  const resp = await request(
+    args.baseUrl,
+    "/api/v1/app-sessions/exchange",
+    propelToken,
+    {
+      method: "POST",
+      body: { app_id: args.appId, scopes: args.scopes ?? [] },
+      fetchImpl: args.fetchImpl,
+      sleepImpl: args.sleepImpl
+    }
+  );
+  return resp.data ?? resp;
+}
+async function exchangeServiceToken(args) {
+  const resp = await request(
+    args.baseUrl,
+    "/api/v1/service-token",
+    "",
+    {
+      method: "POST",
+      body: {
+        client_id: args.clientId,
+        client_secret: args.clientSecret,
+        scopes: args.scopes ?? [],
+        ttl_seconds: args.ttlSeconds ?? null
+      },
+      fetchImpl: args.fetchImpl,
+      sleepImpl: args.sleepImpl
+    }
+  );
+  return resp.data ?? resp;
+}
+
+// src/appClient.ts
+function createGraph8AppClient(config) {
+  if (typeof config?.getPropelAuthToken !== "function") {
+    throw new Error(
+      "createGraph8AppClient requires getPropelAuthToken() \u2014 a function returning the caller's PropelAuth token"
+    );
+  }
+  const asRecord = config;
+  if ("apiKey" in asRecord || "writeKey" in asRecord) {
+    throw new Error(
+      "createGraph8AppClient does not accept an org API key or write key in the browser \u2014 pass getPropelAuthToken() instead"
+    );
+  }
+  const baseUrl = config.apiUrl || DEFAULT_APP_API;
+  const tokens = createTokenManager({
+    now: config.now,
+    refreshSkewMs: config.refreshSkewMs,
+    refresh: () => exchangeBrowserToken({
+      baseUrl,
+      appId: config.appId,
+      scopes: config.scopes,
+      getPropelAuthToken: config.getPropelAuthToken,
+      fetchImpl: config.fetchImpl,
+      sleepImpl: config.sleepImpl
+    })
+  });
+  const req = createAppRequester({ baseUrl, tokens, fetchImpl: config.fetchImpl, sleepImpl: config.sleepImpl });
+  return {
+    appId: config.appId,
+    tenantOrgId: config.tenantOrgId,
+    request: req,
+    getAppToken: (force = false) => tokens.getToken(force)
+  };
+}
+function createGraph8ServiceClient(config) {
+  if (!config?.clientId || !config?.clientSecret) {
+    throw new Error("createGraph8ServiceClient requires clientId and clientSecret");
+  }
+  if (!config?.tenantOrgId) {
+    throw new Error(
+      "createGraph8ServiceClient requires tenantOrgId \u2014 the single consented client org this backend acts for"
+    );
+  }
+  const baseUrl = config.apiUrl || DEFAULT_APP_API;
+  const tokens = createTokenManager({
+    now: config.now,
+    refreshSkewMs: config.refreshSkewMs,
+    refresh: () => exchangeServiceToken({
+      baseUrl,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes,
+      ttlSeconds: config.ttlSeconds,
+      fetchImpl: config.fetchImpl,
+      sleepImpl: config.sleepImpl
+    })
+  });
+  const req = createAppRequester({
+    baseUrl,
+    tokens,
+    extraHeaders: { "X-Target-Org-Id": config.tenantOrgId },
+    fetchImpl: config.fetchImpl,
+    sleepImpl: config.sleepImpl
+  });
+  return {
+    tenantOrgId: config.tenantOrgId,
+    request: req,
+    getServiceToken: (force = false) => tokens.getToken(force)
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_APP_API,
   G8Error,
   KNOWN_WEBHOOK_EVENTS,
   WebhookSignatureError,
   backoffDelayMs,
   constructEvent,
+  createAppRequester,
+  createGraph8AppClient,
+  createGraph8ServiceClient,
+  createTokenManager,
+  exchangeBrowserToken,
+  exchangeServiceToken,
   g8,
   isRetryableStatus,
   paginate,