@gradientlabs/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1507 @@
+/** A subset of the global `fetch` signature, so callers can inject their own. */
+type FetchLike = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    text(): Promise<string>;
+}>;
+interface HttpClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    fetch: FetchLike;
+    timeoutMs?: number;
+}
+interface RequestOptions {
+    /** Query parameters. Undefined/null values are omitted. */
+    query?: Record<string, string | number | boolean | undefined | null>;
+    /** JSON request body. Serialised with JSON.stringify. */
+    body?: unknown;
+    /** Caller-supplied cancellation signal. */
+    signal?: AbortSignal;
+}
+/**
+ * Thin wrapper around `fetch` that handles auth, headers, JSON
+ * (de)serialisation, cancellation, and error mapping. It never retries — retry
+ * policy is left entirely to the caller.
+ */
+declare class HttpClient {
+    private readonly config;
+    constructor(config: HttpClientConfig);
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    private buildUrl;
+    private buildSignal;
+}
+
+/** Per-request options accepted by every client method. */
+interface RequestConfig {
+    /** Cancellation signal, the Node equivalent of Go's context.Context. */
+    signal?: AbortSignal;
+}
+
+declare const ArticleStatus: {
+    readonly Draft: "draft";
+    readonly Published: "published";
+    readonly Deleted: "deleted";
+    readonly Excluded: "excluded";
+    readonly Unknown: "unknown";
+};
+type ArticleStatus = (typeof ArticleStatus)[keyof typeof ArticleStatus] | (string & {});
+declare const ArticleUsageStatus: {
+    readonly On: "on";
+    readonly Off: "off";
+};
+type ArticleUsageStatus = (typeof ArticleUsageStatus)[keyof typeof ArticleUsageStatus] | (string & {});
+declare const ArticleVisibility: {
+    readonly Public: "public";
+    readonly Users: "users";
+    readonly Internal: "internal";
+    readonly Unknown: "unknown";
+};
+type ArticleVisibility = (typeof ArticleVisibility)[keyof typeof ArticleVisibility] | (string & {});
+declare const AttachmentType: {
+    readonly Image: "image";
+    readonly File: "file";
+};
+type AttachmentType = (typeof AttachmentType)[keyof typeof AttachmentType] | (string & {});
+declare const Channel: {
+    readonly Web: "web";
+    readonly Email: "email";
+    readonly Voice: "voice";
+    readonly Unmapped: "unmapped";
+};
+type Channel = (typeof Channel)[keyof typeof Channel] | (string & {});
+declare const CustomerSource: {
+    readonly Dixa: "dixa";
+    readonly Intercom: "intercom";
+    readonly Freshchat: "freshchat";
+    readonly Freshdesk: "freshdesk";
+    readonly PublicApi: "public-api";
+    readonly ChatSdk: "chat-sdk";
+    readonly Salesforce: "salesforce";
+    readonly Zendesk: "zendesk";
+    readonly Livekit: "livekit";
+    readonly Twilio: "twilio";
+    readonly Talkdesk: "talkdesk";
+    readonly IntercomVoice: "intercom-voice";
+    readonly Livechat: "livechat";
+    readonly WebApp: "web-app";
+    readonly Gmail: "gmail";
+    readonly File: "file";
+};
+type CustomerSource = (typeof CustomerSource)[keyof typeof CustomerSource] | (string & {});
+declare const ParticipantType: {
+    readonly Customer: "Customer";
+    readonly Agent: "Agent";
+    readonly AIAgent: "AI Agent";
+    readonly Bot: "Bot";
+};
+type ParticipantType = (typeof ParticipantType)[keyof typeof ParticipantType] | (string & {});
+declare const ConversationEventType: {
+    readonly Assigned: "assigned";
+    readonly Cancelled: "cancelled";
+    readonly Finished: "finished";
+    readonly Resumed: "resumed";
+    readonly InternalNote: "internal-note";
+    readonly Message: "message";
+    readonly Delivered: "delivered";
+    readonly Read: "read";
+    readonly Rated: "rated";
+    readonly Started: "started";
+    readonly Typing: "typing";
+    readonly AsyncToolResult: "async-tool-result";
+};
+type ConversationEventType = (typeof ConversationEventType)[keyof typeof ConversationEventType] | (string & {});
+declare const ProcedureStatus: {
+    readonly Unsaved: "unsaved";
+    readonly Draft: "draft";
+    readonly Live: "live";
+    readonly Archived: "archived";
+};
+type ProcedureStatus = (typeof ProcedureStatus)[keyof typeof ProcedureStatus] | (string & {});
+declare const NoteStatus: {
+    readonly Draft: "draft";
+    readonly Live: "live";
+    readonly Deleted: "deleted";
+};
+type NoteStatus = (typeof NoteStatus)[keyof typeof NoteStatus] | (string & {});
+declare const BackOfficeTaskStatus: {
+    readonly Pending: "pending";
+    readonly InProgress: "in-progress";
+    readonly Completed: "completed";
+    readonly Failed: "failed";
+    readonly HandedOff: "handed-off";
+};
+type BackOfficeTaskStatus = (typeof BackOfficeTaskStatus)[keyof typeof BackOfficeTaskStatus] | (string & {});
+declare const BackOfficeTaskResultType: {
+    readonly Custom: "custom";
+};
+type BackOfficeTaskResultType = (typeof BackOfficeTaskResultType)[keyof typeof BackOfficeTaskResultType] | (string & {});
+declare const AttributeCardinality: {
+    readonly One: "one";
+    readonly Many: "many";
+};
+type AttributeCardinality = (typeof AttributeCardinality)[keyof typeof AttributeCardinality] | (string & {});
+declare const AttributeType: {
+    readonly String: "string";
+    readonly Date: "date";
+    readonly Timestamp: "timestamp";
+    readonly Boolean: "boolean";
+    readonly Number: "number";
+    readonly Array: "array";
+    readonly Complex: "complex";
+};
+type AttributeType = (typeof AttributeType)[keyof typeof AttributeType] | (string & {});
+declare const ResourceSourceRefreshStrategy: {
+    readonly Dynamic: "dynamic";
+    readonly Static: "static";
+};
+type ResourceSourceRefreshStrategy = (typeof ResourceSourceRefreshStrategy)[keyof typeof ResourceSourceRefreshStrategy] | (string & {});
+declare const ResourceSourceScope: {
+    readonly Global: "global";
+    readonly Local: "local";
+};
+type ResourceSourceScope = (typeof ResourceSourceScope)[keyof typeof ResourceSourceScope] | (string & {});
+declare const ResourceSourceType: {
+    readonly Http: "http";
+    readonly Internal: "internal";
+    readonly Webhook: "webhook";
+};
+type ResourceSourceType = (typeof ResourceSourceType)[keyof typeof ResourceSourceType] | (string & {});
+declare const SchemaUpdateStrategy: {
+    readonly Replace: "replace";
+    readonly Merge: "merge";
+};
+type SchemaUpdateStrategy = (typeof SchemaUpdateStrategy)[keyof typeof SchemaUpdateStrategy] | (string & {});
+declare const ResourceTypeRefreshStrategy: {
+    readonly Dynamic: "dynamic";
+    readonly Static: "static";
+};
+type ResourceTypeRefreshStrategy = (typeof ResourceTypeRefreshStrategy)[keyof typeof ResourceTypeRefreshStrategy] | (string & {});
+declare const ResourceTypeScope: {
+    readonly Global: "global";
+    readonly Local: "local";
+};
+type ResourceTypeScope = (typeof ResourceTypeScope)[keyof typeof ResourceTypeScope] | (string & {});
+declare const SupportPlatform: {
+    readonly Dixa: "dixa";
+    readonly Freshchat: "freshchat";
+    readonly Freshdesk: "freshdesk";
+    readonly Gmail: "gmail";
+    readonly Intercom: "intercom";
+    readonly Livechat: "livechat";
+    readonly PublicApi: "public-api";
+    readonly ChatSdk: "chat-sdk";
+    readonly Salesforce: "salesforce";
+    readonly Zendesk: "zendesk";
+    readonly Livekit: "livekit";
+    readonly Twilio: "twilio";
+    readonly Talkdesk: "talkdesk";
+    readonly IntercomVoice: "intercom-voice";
+    readonly ConversationSynthesizor: "conversation-synthesizor";
+    readonly WebApp: "web-app";
+};
+type SupportPlatform = (typeof SupportPlatform)[keyof typeof SupportPlatform] | (string & {});
+declare const BodyEncoding: {
+    readonly Json: "application/json";
+    readonly Form: "application/x-www-form-urlencoded";
+};
+type BodyEncoding = (typeof BodyEncoding)[keyof typeof BodyEncoding] | (string & {});
+declare const ParameterSource: {
+    readonly Llm: "llm";
+    readonly Literal: "literal";
+    readonly Resource: "resource";
+};
+type ParameterSource = (typeof ParameterSource)[keyof typeof ParameterSource] | (string & {});
+declare const ParameterType: {
+    readonly String: "string";
+    readonly StringArray: "string_array";
+    readonly Integer: "integer";
+    readonly Float: "float";
+    readonly Boolean: "boolean";
+    readonly Date: "date";
+    readonly Timestamp: "timestamp";
+    readonly Duration: "duration";
+};
+type ParameterType = (typeof ParameterType)[keyof typeof ParameterType] | (string & {});
+
+interface UpsertArticleParams {
+    /** External identifier the company uses for this article. */
+    id: string;
+    author_id: string;
+    title: string;
+    description: string;
+    body: string;
+    visibility: ArticleVisibility;
+    /** External identifier of the topic this article belongs to. */
+    topic_id: string;
+    status: ArticleStatus;
+    /** Additional meta-data about the article. */
+    data: Record<string, unknown>;
+    created: string;
+    last_edited: string;
+    public_url: string;
+}
+interface SetArticleUsageStatusParams {
+    usage_status: ArticleUsageStatus;
+}
+/** An article topic. */
+interface Topic {
+    Source: string;
+    ExternalID: string;
+    Name: string;
+    Description: string;
+    Visibility: ArticleVisibility;
+    ParentExternalID: string;
+    Created: string;
+    LastEdited: string;
+    LastSeen: string;
+    /** Base64-encoded raw representation of the topic from the support platform. */
+    Data: string;
+    PublicURL: string;
+}
+interface ListTopicsParams {
+    /** Which platform's topics to read. Defaults to "public-api". */
+    support_platform?: string;
+}
+interface ReadTopicParams {
+    /** Which platform's topic to read. Defaults to "public-api". */
+    support_platform?: string;
+}
+interface UpsertTopicParams {
+    /** External identifier the company uses for this topic. */
+    id: string;
+    /** External identifier of this topic's parent topic. */
+    parent_id: string;
+    name: string;
+    description: string;
+    visibility: ArticleVisibility;
+    status: ArticleStatus;
+    data: Record<string, unknown>;
+    created: string;
+    last_edited: string;
+    public_url: string;
+}
+
+/**
+ * Article management endpoints. Requires a Management API key.
+ */
+declare class Articles {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Creates or updates a help article. */
+    upsert(params: UpsertArticleParams, config?: RequestConfig): Promise<void>;
+    /** Updates whether the AI agent can use an article or not. */
+    setUsageStatus(id: string, params: SetArticleUsageStatusParams, config?: RequestConfig): Promise<void>;
+    /** Marks an article as deleted. */
+    delete(id: string, config?: RequestConfig): Promise<void>;
+}
+
+/** An attachment uploaded with a back-office task. URL and base64 are mutually exclusive. */
+interface BackOfficeTaskAttachmentInput {
+    file_name: string;
+    url?: string;
+    base_64_contents?: string;
+}
+/** An attachment as returned on a back-office task. */
+interface BackOfficeTaskAttachment {
+    idempotency_key: string;
+    file_name: string;
+    external_url?: string;
+    raw_contents?: string;
+}
+/** The result of a back-office task, validated against the procedure's result schema. */
+interface BackOfficeTaskResult {
+    result_type: BackOfficeTaskResultType;
+    custom?: Record<string, unknown>;
+}
+/** A back-office (Tier 2) task processed by a configurable agent. */
+interface BackOfficeTask {
+    id: string;
+    agent_id: string;
+    input: Record<string, unknown>;
+    created: string;
+    updated?: string;
+    status?: BackOfficeTaskStatus;
+    result?: BackOfficeTaskResult;
+    metadata?: Record<string, string>;
+    attachments?: BackOfficeTaskAttachment[];
+    completed?: string;
+    failed?: string;
+    failure_reasons?: string[];
+    handed_off?: string;
+    hand_off_reason?: string;
+}
+interface CreateBackOfficeTaskParams {
+    /** Unique external identifier for the task. */
+    id: string;
+    /** Input data for the task; shape depends on the task type. */
+    input: Record<string, unknown>;
+    /** Identifies the configurable back-office agent to run the task against. Required. */
+    agent_id: string;
+    /** Optional free-format metadata the agent can read. */
+    metadata?: Record<string, string>;
+    attachments?: BackOfficeTaskAttachmentInput[];
+    /** Optional creation timestamp (RFC3339). Defaults to now. */
+    created?: string;
+}
+
+/**
+ * Back-office task endpoints. Requires an Integration API key.
+ */
+declare class BackOfficeTasks {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Creates a new back-office task. */
+    create(params: CreateBackOfficeTaskParams, config?: RequestConfig): Promise<BackOfficeTask>;
+    /** Retrieves detailed information about a back-office task. */
+    get(id: string, config?: RequestConfig): Promise<BackOfficeTask>;
+}
+
+/** Basic information about a user, e.g. the author of a procedure. */
+interface UserDetails {
+    email: string;
+}
+/** A file or media item attached to a conversation message. */
+interface Attachment {
+    type: AttachmentType;
+    /** Original file name including extension. */
+    file_name: string;
+    /** Publicly accessible URL where the attachment can be downloaded. */
+    url: string;
+    /** Optional short summary of what the attachment is. */
+    summary?: string;
+    /** Optional full textual extract of the attachment's contents. */
+    description?: string;
+}
+
+/** Agent-derived metadata about how a conversation was processed. */
+interface AgentMetadata {
+    intent: string;
+    intent_handoff_target: string;
+    handoff_reason: string;
+    handoff_note: string;
+}
+/** A series of messages between a customer, human agent, and the AI agent. */
+interface Conversation {
+    id: string;
+    customer_id: string;
+    channel: Channel;
+    created: string;
+    updated: string;
+    status: string;
+    /** Whether an AI agent is currently actively handling this conversation. */
+    agent_is_active: boolean;
+    latest_intent: string;
+    latest_handoff_target: string;
+    latest_agent_metadata?: AgentMetadata;
+}
+/** A single message within a conversation. */
+interface Message {
+    id: string;
+    body: string;
+    participant_id: string;
+    participant_type: ParticipantType;
+    subject?: string;
+    attachments?: Attachment[];
+    created?: string;
+    conversation_token?: string;
+}
+interface StartConversationParams {
+    /** Unique external identifier for the conversation. */
+    id: string;
+    /** Unique external identifier for the customer. */
+    customer_id: string;
+    channel: Channel;
+    /** Optional identifier of the participant the conversation is assigned to. */
+    assignee_id?: string;
+    /** Set to "AI Agent" to assign the conversation to the Gradient Labs AI. */
+    assignee_type?: ParticipantType;
+    /** Arbitrary metadata attached to the conversation; echoed back in webhooks. */
+    metadata?: unknown;
+    /** Optional creation timestamp (RFC3339). Defaults to now. */
+    created?: string;
+    /** Structured context data the AI agent can use, keyed by resource type. */
+    resources?: Record<string, unknown>;
+    /** Optional traffic group to scope which procedures the conversation can access. */
+    traffic_group_id?: string;
+    /** Raw sensitive token echoed back in future tool/webhook calls. */
+    conversation_token?: string;
+}
+interface AddMessageParams {
+    id: string;
+    body?: string;
+    participant_id: string;
+    participant_type: ParticipantType;
+    subject?: string;
+    attachments?: Attachment[];
+    created?: string;
+    conversation_token?: string;
+}
+interface AssignConversationParams {
+    assignee_type: ParticipantType;
+    assignee_id?: string;
+    reason?: string;
+    timestamp?: string;
+}
+interface ResumeConversationParams {
+    assignee_type: ParticipantType;
+    resources?: Record<string, unknown>;
+    assignee_id?: string;
+    reason?: string;
+    timestamp?: string;
+}
+interface CancelConversationParams {
+    reason?: string;
+    timestamp?: string;
+}
+interface FinishConversationParams {
+    reason?: string;
+    timestamp?: string;
+}
+interface ConversationEventParams {
+    type: ConversationEventType;
+    participant_id: string;
+    participant_type: ParticipantType;
+    body?: string;
+    message_id?: string;
+    idempotency_key?: string;
+    timestamp?: string;
+}
+interface RateConversationParams {
+    type: string;
+    value: number;
+    max_value: number;
+    min_value: number;
+    comments?: string;
+    timestamp?: string;
+}
+interface ReturnAsyncToolResultParams {
+    async_tool_execution_id: string;
+    /** Required by the API: the JSON result of the async tool execution. */
+    payload: Record<string, unknown>;
+    timestamp?: string;
+}
+interface ReadConversationParams {
+    /** Which platform's conversation to read. Defaults to "public-api". */
+    support_platform?: string;
+}
+interface StartOutboundConversationParams {
+    customer_id: string;
+    customer_source: CustomerSource;
+    procedure_id: string;
+    channel?: Channel;
+    support_platform?: string;
+    body?: string;
+    subject?: string;
+    resources?: Record<string, unknown>;
+}
+interface OutboundConversation {
+    conversation_id: string;
+}
+
+/**
+ * Conversation endpoints. Requires an Integration API key.
+ */
+declare class Conversations {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Begins a conversation. */
+    start(params: StartConversationParams, config?: RequestConfig): Promise<Conversation>;
+    /** Retrieves a conversation, including the latest AI agent metadata. */
+    get(id: string, params?: ReadConversationParams, config?: RequestConfig): Promise<Conversation>;
+    /**
+     * Retrieves a conversation.
+     *
+     * @deprecated Use {@link Conversations.get} instead, which reads from the
+     * canonical `/read` endpoint.
+     */
+    getDeprecated(id: string, config?: RequestConfig): Promise<Conversation>;
+    /** Adds a new message to an existing conversation. */
+    addMessage(id: string, params: AddMessageParams, config?: RequestConfig): Promise<Message>;
+    /** Transfers responsibility for handling a conversation to a participant. */
+    assign(id: string, params: AssignConversationParams, config?: RequestConfig): Promise<void>;
+    /** Logs an event against the conversation (e.g. typing, delivered, read). */
+    addEvent(id: string, params: ConversationEventParams, config?: RequestConfig): Promise<void>;
+    /** Adds the result of a customer survey (e.g. CSAT) to a conversation. */
+    rate(id: string, params: RateConversationParams, config?: RequestConfig): Promise<void>;
+    /** Cancels a conversation (e.g. because a human has taken it over). */
+    cancel(id: string, params?: CancelConversationParams, config?: RequestConfig): Promise<void>;
+    /** Finishes a conversation that has reached a natural end state. */
+    finish(id: string, params?: FinishConversationParams, config?: RequestConfig): Promise<void>;
+    /** Re-opens a conversation that was previously finished. */
+    resume(id: string, params: ResumeConversationParams, config?: RequestConfig): Promise<void>;
+    /** Returns the result of an async tool execution. */
+    returnAsyncToolResult(id: string, params: ReturnAsyncToolResultParams, config?: RequestConfig): Promise<void>;
+}
+
+/** A hand-off target (team, agent, or queue) a conversation can be routed to. */
+interface HandOffTarget {
+    id: string;
+    name: string;
+}
+interface UpsertHandOffTargetParams {
+    id: string;
+    name: string;
+}
+interface DeleteHandOffTargetParams {
+    id: string;
+}
+interface GetDefaultHandOffTargetParams {
+    /** The conversation channel to get the default for. */
+    channel: string;
+}
+interface SetDefaultHandOffTargetParams {
+    /** Target ID to set as default. Empty string clears the default. */
+    id: string;
+    channel: string;
+}
+
+/**
+ * Hand-off target management endpoints. Requires a Management API key.
+ */
+declare class HandOffTargets {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists the available hand-off targets. */
+    list(config?: RequestConfig): Promise<HandOffTarget[]>;
+    /** Creates or updates a hand-off target. */
+    upsert(params: UpsertHandOffTargetParams, config?: RequestConfig): Promise<void>;
+    /** Deletes a hand-off target. */
+    delete(params: DeleteHandOffTargetParams, config?: RequestConfig): Promise<void>;
+    /** Gets the current default hand-off target for a channel. Returns "" if unset. */
+    getDefault(params: GetDefaultHandOffTargetParams, config?: RequestConfig): Promise<string>;
+    /** Sets the default hand-off target for a channel. */
+    setDefault(params: SetDefaultHandOffTargetParams, config?: RequestConfig): Promise<void>;
+}
+
+/** The IP addresses Gradient Labs uses, in CIDR format. */
+interface IpAddresses {
+    /** Addresses the public API is served from. */
+    api: string[];
+    /** Addresses outbound (egress) requests originate from. */
+    egress: string[];
+}
+/**
+ * IP address endpoints. Requires a Management API key.
+ */
+declare class IpAddressesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Returns the list of IP addresses Gradient Labs uses, in CIDR format. */
+    list(config?: RequestConfig): Promise<IpAddresses>;
+}
+
+/** A note that provides the AI agent with time-bound context. */
+interface Note {
+    /** Gradient Labs' internal ID for this note. */
+    gradient_labs_id: string;
+    /** The company's external ID for this note. */
+    id: string;
+    title: string;
+    body: string;
+    url: string;
+    valid_from: string;
+    valid_to: string;
+    last_modified_by: string;
+    created: string;
+    updated: string;
+    status: NoteStatus;
+}
+interface CreateNoteParams {
+    /** External identifier the company uses for this note. */
+    id: string;
+    title: string;
+    /** Main contents of the note. Mutually exclusive with webpage_url. */
+    body: string;
+    /** Webpage to use as the note body. Mutually exclusive with body. */
+    webpage_url: string;
+    /** When the note becomes relevant. */
+    start_time: string;
+    /** When the note is no longer relevant. */
+    end_time: string;
+}
+interface UpdateNoteParams {
+    title: string;
+    body: string;
+    webpage_url: string;
+    start_time: string;
+    end_time: string;
+}
+interface SetNoteStatusParams {
+    status: NoteStatus;
+}
+
+/**
+ * Note management endpoints. Requires a Management API key.
+ */
+declare class Notes {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Creates a new note. */
+    create(params: CreateNoteParams, config?: RequestConfig): Promise<Note>;
+    /** Updates an existing note's contents. */
+    update(id: string, params: UpdateNoteParams, config?: RequestConfig): Promise<Note>;
+    /** Updates a note's status. */
+    setStatus(id: string, params: SetNoteStatusParams, config?: RequestConfig): Promise<void>;
+    /** Marks a note as deleted. */
+    delete(id: string, config?: RequestConfig): Promise<void>;
+}
+
+/**
+ * Outbound conversation endpoints. Requires an Integration API key.
+ */
+declare class OutboundConversations {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Creates and starts a new outbound conversation initiated by the AI agent. */
+    start(params: StartOutboundConversationParams, config?: RequestConfig): Promise<OutboundConversation>;
+}
+
+/**
+ * Cursor-based pagination metadata returned by list endpoints. Cursors are
+ * opaque strings; pass `next`/`prev` back via the `after`/`before` parameters
+ * to page through results.
+ */
+interface PageInfo {
+    next?: string;
+    prev?: string;
+}
+/** A single page of a paginated list response. */
+interface Page<T> {
+    data: T[];
+    pageInfo: PageInfo;
+}
+
+/** An AI agent procedure that defines how the agent should handle conversations. */
+interface Procedure {
+    id: string;
+    name: string;
+    description: string;
+    status: ProcedureStatus;
+    author: UserDetails;
+    created: string;
+    updated: string;
+    has_daily_limit: boolean;
+    max_daily_conversations: number;
+}
+/** Configuration limiting a gated procedure version. */
+interface GatedConfig {
+    MaxDailyConversations: number;
+}
+/** A specific saved version of a procedure. */
+interface ProcedureVersion {
+    Name: string;
+    Description: string;
+    Version: number;
+    Author: string;
+    Created: string;
+    Gated: boolean;
+    /** Present only when the version is gated. */
+    GatedConfig?: GatedConfig;
+    Live: boolean;
+}
+interface ListProceduresParams {
+    /** Opaque pagination cursor from a previous response. */
+    cursor?: string;
+    /** Filter by status, e.g. "live" or "draft". */
+    status?: ProcedureStatus;
+}
+interface SetProcedureLimitParams {
+    has_daily_limit?: boolean;
+    max_daily_conversations?: number;
+}
+interface SetGatedVersionParams {
+    max_daily_conversations: number;
+    /** Replace an existing gated version if one exists. */
+    replace: boolean;
+}
+
+/**
+ * Procedure management endpoints. Requires a Management API key.
+ */
+declare class Procedures {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Retrieves one page of procedures. */
+    list(params?: ListProceduresParams, config?: RequestConfig): Promise<Page<Procedure>>;
+    /** Iterates over all procedures, transparently following pagination cursors. */
+    listAll(params?: Omit<ListProceduresParams, "cursor">, config?: RequestConfig): AsyncGenerator<Procedure, void, undefined>;
+    /** Retrieves a specific procedure by ID. */
+    get(id: string, config?: RequestConfig): Promise<Procedure>;
+    /** Configures daily usage limits for a procedure. Returns the updated procedure. */
+    setLimit(id: string, params: SetProcedureLimitParams, config?: RequestConfig): Promise<Procedure>;
+    /** Lists the non-ephemeral versions of a procedure. */
+    listVersions(id: string, config?: RequestConfig): Promise<ProcedureVersion[]>;
+    /** Promotes a procedure version to be the live (production) version. */
+    setLiveVersion(id: string, version: number, config?: RequestConfig): Promise<void>;
+    /** Removes a procedure version from being the live revision. */
+    unsetLiveVersion(id: string, version: number, config?: RequestConfig): Promise<void>;
+    /** Marks a procedure version as gated for A/B testing. */
+    setGatedVersion(id: string, version: number, params: SetGatedVersionParams, config?: RequestConfig): Promise<void>;
+    /** Removes the gated marking from a procedure version. */
+    unsetGatedVersion(id: string, version: number, config?: RequestConfig): Promise<void>;
+}
+
+/** A single data field within a resource schema. */
+interface Attribute {
+    path: string;
+    type: AttributeType;
+    cardinality: AttributeCardinality;
+    description: string;
+    is_root: boolean;
+    name: string;
+}
+/** The structure of data provided by a resource source or type. */
+interface Schema {
+    /** The complete JSON schema definition in its original format. */
+    raw: Record<string, unknown>;
+    attributes?: Attribute[];
+}
+/** HTTP body configuration for a resource source. */
+interface ResourceSourceHttpBodyDefinition {
+    encoding: string;
+    json_template?: string;
+    form_field_templates?: Record<string, string>;
+}
+/** HTTP configuration for a resource source. */
+interface ResourceSourceHttpConfig {
+    method: string;
+    url_template: string;
+    header_templates?: Record<string, string>;
+    body?: ResourceSourceHttpBodyDefinition;
+}
+/** Webhook configuration for a resource source. */
+interface ResourceSourceWebhookConfig {
+    name: string;
+}
+/** A data source that provides structured information to AI agents. */
+interface ResourceSource {
+    id: string;
+    display_name: string;
+    description: string;
+    source_type: ResourceSourceType;
+    available_refresh_strategies: ResourceSourceRefreshStrategy[];
+    available_scopes: ResourceSourceScope[];
+    created: string;
+    updated: string;
+    attribute_descriptions?: Record<string, string>;
+    schema?: Schema;
+    http_config?: ResourceSourceHttpConfig;
+    webhook_config?: ResourceSourceWebhookConfig;
+}
+interface CreateResourceSourceParams {
+    display_name: string;
+    source_type: ResourceSourceType;
+    description?: string;
+    attribute_descriptions?: Record<string, string>;
+    http_config?: ResourceSourceHttpConfig;
+    webhook_config?: ResourceSourceWebhookConfig;
+}
+interface UpdateResourceSourceParams {
+    display_name?: string;
+    description?: string;
+    source_type?: ResourceSourceType;
+    attribute_descriptions?: Record<string, string>;
+    schema?: Schema;
+    http_config?: ResourceSourceHttpConfig;
+    webhook_config?: ResourceSourceWebhookConfig;
+}
+interface UpdateSchemaByExamplesParams {
+    /** Resource payload examples to infer the schema from. */
+    examples: Record<string, unknown>[];
+    schema_update_strategy?: SchemaUpdateStrategy;
+}
+/** How a resource type connects to and retrieves data from a source. */
+interface SourceConfig {
+    source_id: string;
+    /** Which attributes to include. Empty means all. */
+    attributes: string[];
+    /** Cache duration, e.g. "1h", "30m", "never". */
+    cache: string;
+}
+/** A specific type of structured data accessible by AI agents. */
+interface ResourceType {
+    id: string;
+    display_name: string;
+    description: string;
+    scope: ResourceTypeScope;
+    refresh_strategy: ResourceTypeRefreshStrategy;
+    is_enabled: boolean;
+    created: string;
+    updated: string;
+    schema?: Schema;
+    source_config?: SourceConfig;
+}
+interface CreateResourceTypeParams {
+    display_name: string;
+    scope: ResourceTypeScope;
+    refresh_strategy: ResourceTypeRefreshStrategy;
+    description?: string;
+    is_enabled?: boolean;
+    source_config?: SourceConfig;
+}
+interface UpdateResourceTypeParams {
+    display_name?: string;
+    description?: string;
+    scope?: ResourceTypeScope;
+    refresh_strategy?: ResourceTypeRefreshStrategy;
+    is_enabled?: boolean;
+    source_config?: SourceConfig;
+}
+
+/**
+ * Resource source management endpoints. Requires a Management API key.
+ */
+declare class ResourceSources {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists all resource sources accessible to the company. */
+    list(config?: RequestConfig): Promise<ResourceSource[]>;
+    /** Creates a new resource source. */
+    create(params: CreateResourceSourceParams, config?: RequestConfig): Promise<ResourceSource>;
+    /** Retrieves a specific resource source by ID. */
+    get(id: string, config?: RequestConfig): Promise<ResourceSource>;
+    /** Updates an existing resource source. */
+    update(id: string, params: UpdateResourceSourceParams, config?: RequestConfig): Promise<ResourceSource>;
+    /** Deletes a resource source. */
+    delete(id: string, config?: RequestConfig): Promise<void>;
+    /** Modifies the source schema based on the provided payload examples. */
+    updateSchemaByExamples(id: string, params: UpdateSchemaByExamplesParams, config?: RequestConfig): Promise<ResourceSource>;
+}
+
+/**
+ * Resource type management endpoints. Requires a Management API key.
+ */
+declare class ResourceTypes {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists all resource types accessible to the company. */
+    list(config?: RequestConfig): Promise<ResourceType[]>;
+    /** Creates a new resource type. */
+    create(params: CreateResourceTypeParams, config?: RequestConfig): Promise<ResourceType>;
+    /** Retrieves a specific resource type by ID. */
+    get(id: string, config?: RequestConfig): Promise<ResourceType>;
+    /** Updates an existing resource type. */
+    update(id: string, params: UpdateResourceTypeParams, config?: RequestConfig): Promise<ResourceType>;
+    /** Deletes a resource type. */
+    delete(id: string, config?: RequestConfig): Promise<void>;
+}
+
+/** Request body configuration for an HTTP tool. */
+interface HttpBodyDefinition {
+    encoding: BodyEncoding;
+    /** JSON body template when encoding is "application/json". */
+    json_template?: string;
+    /** Form fields when encoding is form-encoded. */
+    form_field_templates?: Record<string, string>;
+}
+/** Configures a tool to make direct HTTP requests to external APIs. */
+interface HttpDefinition {
+    method: string;
+    /** URL with `${params.name}` substitution. */
+    url_template: string;
+    header_templates?: Record<string, string>;
+    body?: HttpBodyDefinition;
+}
+/** Configures a tool to call a webhook. */
+interface ToolWebhookConfiguration {
+    name: string;
+}
+/** Configures a tool to execute via a Temporal workflow. */
+interface WorkflowConfiguration {
+    workflow_type: string;
+    task_queue: string;
+}
+/** Configures a tool to execute via a Model Context Protocol server. */
+interface McpConfiguration {
+    server_id: string;
+    external_tool_name: string;
+}
+/** A tool configuration embedded within another tool (e.g. async start/cancel). */
+interface ChildTool {
+    http?: HttpDefinition;
+    webhook?: ToolWebhookConfiguration;
+    workflow?: WorkflowConfiguration;
+}
+/**
+ * Configures a tool for long-running asynchronous operations.
+ *
+ * `timeout` is a duration in nanoseconds (the API's native representation).
+ */
+interface AsyncDefinition {
+    start_execution_tool: ChildTool;
+    /** Maximum duration to wait, in nanoseconds. */
+    timeout: number;
+    cancel_execution_tool?: ChildTool;
+}
+/** A predefined choice for a tool parameter. */
+interface ParameterOption {
+    value: string;
+    text: string;
+}
+/** An input parameter a tool accepts when invoked. */
+interface ToolParameter {
+    name: string;
+    description: string;
+    type: ParameterType;
+    allowed_sources: ParameterSource[];
+    /** If nil, defaults to true (required). */
+    required?: boolean;
+    options?: ParameterOption[];
+}
+/** A group of parameters that become active for a discriminator value. */
+interface ToolParameterSet {
+    discriminator_parameter_name: string;
+    discriminator_value: string;
+    parameters: ToolParameter[];
+}
+/** A custom tool the AI agent can use during conversations. */
+interface Tool {
+    id: string;
+    name: string;
+    description: string;
+    parameters: ToolParameter[];
+    parameter_sets?: ToolParameterSet[];
+    draft?: boolean;
+    http?: HttpDefinition;
+    webhook?: ToolWebhookConfiguration;
+    async?: AsyncDefinition;
+    mcp?: McpConfiguration;
+}
+interface CreateToolParams {
+    id: string;
+    name: string;
+    description: string;
+    parameters: ToolParameter[];
+    parameter_sets?: ToolParameterSet[];
+    draft?: boolean;
+    http?: HttpDefinition;
+    webhook?: ToolWebhookConfiguration;
+    async?: AsyncDefinition;
+    mcp?: McpConfiguration;
+}
+interface UpdateToolParams {
+    description: string;
+    parameters: ToolParameter[];
+    http?: HttpDefinition;
+    webhook?: ToolWebhookConfiguration;
+    async?: AsyncDefinition;
+}
+interface ReadToolParams {
+    /** Read a specific tool version. */
+    version?: number;
+}
+/** A name/value argument passed to a tool execution. */
+interface ToolArgument {
+    name: string;
+    value: string;
+}
+interface ExecuteToolParams {
+    arguments: ToolArgument[];
+    /** Optional conversation-scoped token, if the tool requires one. */
+    token?: string;
+}
+interface ToolExecutionResult {
+    id: string;
+    /** JSON result of the execution, if it succeeded. */
+    result?: Record<string, unknown>;
+    /** Error that occurred during execution, if it failed. */
+    error?: string;
+}
+
+/** HTTP mechanism for refreshing a secret's value. */
+interface RefreshMechanismHttp {
+    request_definition: HttpDefinition;
+    /** Name of the parameter in the (JSON) response body. */
+    response_param_name: string;
+}
+/** A configured secret. The value itself is never returned. */
+interface Secret {
+    name: string;
+    created: string;
+    updated: string;
+    expiry?: string;
+    refresh_mechanism_http?: RefreshMechanismHttp;
+}
+interface WriteSecretParams {
+    value: string;
+    expiry?: string;
+    refresh_mechanism_http?: RefreshMechanismHttp;
+}
+
+/**
+ * Secret management endpoints. Requires a Management API key.
+ */
+declare class Secrets {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists the company's configured secrets. */
+    list(config?: RequestConfig): Promise<Secret[]>;
+    /** Creates or updates a secret. */
+    write(name: string, params: WriteSecretParams, config?: RequestConfig): Promise<Secret>;
+    /** Revokes a secret so it can no longer be used. */
+    revoke(name: string, config?: RequestConfig): Promise<void>;
+}
+
+/** A term the agent should avoid and its replacement, optionally resource-scoped. */
+interface TerminologySubstitution {
+    id: string;
+    blocked: string;
+    blocked_description: string;
+    replacement: string;
+    resource_type_id: string;
+    resource_attribute_json_path: string;
+    resource_value_to_match: string;
+    created: string;
+    updated: string;
+}
+interface CreateTerminologySubstitutionParams {
+    blocked: string;
+    blocked_description: string;
+    replacement: string;
+    resource_type_id?: string;
+    resource_attribute_json_path?: string;
+    resource_value_to_match?: string;
+}
+interface UpdateTerminologySubstitutionParams {
+    blocked: string;
+    blocked_description: string;
+    replacement: string;
+    resource_type_id?: string;
+    resource_attribute_json_path?: string;
+    resource_value_to_match?: string;
+}
+
+/**
+ * Terminology substitution management endpoints. Requires a Management API key.
+ */
+declare class TerminologySubstitutions {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Returns all terminology substitutions configured for the organization. */
+    list(config?: RequestConfig): Promise<TerminologySubstitution[]>;
+    /** Creates a new terminology substitution. */
+    create(params: CreateTerminologySubstitutionParams, config?: RequestConfig): Promise<TerminologySubstitution>;
+    /** Returns a single terminology substitution by ID. */
+    get(id: string, config?: RequestConfig): Promise<TerminologySubstitution>;
+    /** Updates an existing terminology substitution. */
+    update(id: string, params: UpdateTerminologySubstitutionParams, config?: RequestConfig): Promise<TerminologySubstitution>;
+    /** Deletes a terminology substitution by ID. */
+    delete(id: string, config?: RequestConfig): Promise<void>;
+}
+
+/**
+ * Tool management endpoints. Requires a Management API key.
+ */
+declare class Tools {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Returns all tools created by the company. */
+    list(config?: RequestConfig): Promise<Tool[]>;
+    /** Creates a new custom tool. */
+    create(params: CreateToolParams, config?: RequestConfig): Promise<Tool>;
+    /** Reads a tool by ID and optional version. */
+    get(id: string, params?: ReadToolParams, config?: RequestConfig): Promise<Tool>;
+    /** Creates a new revision of a tool. The name and type cannot be changed. */
+    update(id: string, params: UpdateToolParams, config?: RequestConfig): Promise<Tool>;
+    /** Deletes a tool. */
+    delete(id: string, config?: RequestConfig): Promise<void>;
+    /** Executes a tool, enabling you to test it without an actual conversation. */
+    execute(id: string, params: ExecuteToolParams, config?: RequestConfig): Promise<ToolExecutionResult>;
+}
+
+/**
+ * Article topic management endpoints. Requires a Management API key.
+ */
+declare class Topics {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists the company's topics, optionally filtered by support platform. */
+    list(params?: ListTopicsParams, config?: RequestConfig): Promise<Topic[]>;
+    /** Reads a single article topic. */
+    get(id: string, params?: ReadTopicParams, config?: RequestConfig): Promise<Topic>;
+    /** Creates or updates an article topic. */
+    upsert(params: UpsertTopicParams, config?: RequestConfig): Promise<void>;
+}
+
+/** An assigned or excluded target within a traffic group. */
+interface TrafficGroupTarget {
+    target_type: string;
+    target_id: string;
+}
+/** A traffic group scoping which procedures conversations can access. */
+interface TrafficGroup {
+    id: string;
+    name: string;
+    targets: TrafficGroupTarget[];
+    excluded_targets: TrafficGroupTarget[];
+}
+interface CreateTrafficGroupParams {
+    name: string;
+}
+interface UpdateTrafficGroupParams {
+    name: string;
+}
+interface TrafficGroupTargetParams {
+    /** Type of target, e.g. "procedure". */
+    target_type: string;
+    target_id: string;
+}
+
+/**
+ * Traffic group management endpoints. Requires a Management API key.
+ */
+declare class TrafficGroups {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists all traffic groups for the company. */
+    list(config?: RequestConfig): Promise<TrafficGroup[]>;
+    /** Creates a new traffic group. */
+    create(params: CreateTrafficGroupParams, config?: RequestConfig): Promise<TrafficGroup>;
+    /** Updates an existing traffic group. */
+    update(id: string, params: UpdateTrafficGroupParams, config?: RequestConfig): Promise<TrafficGroup>;
+    /** Deletes a traffic group and all associated targets. */
+    delete(id: string, config?: RequestConfig): Promise<void>;
+    /** Adds a target to a traffic group. */
+    addTarget(id: string, params: TrafficGroupTargetParams, config?: RequestConfig): Promise<TrafficGroupTarget>;
+    /** Removes a target from a traffic group. */
+    removeTarget(id: string, targetId: string, config?: RequestConfig): Promise<void>;
+    /** Excludes a target (e.g. a procedure) from a traffic group. */
+    addExclusion(id: string, params: TrafficGroupTargetParams, config?: RequestConfig): Promise<TrafficGroupTarget>;
+    /** Removes a target exclusion from a traffic group. */
+    removeExclusion(id: string, targetId: string, config?: RequestConfig): Promise<void>;
+}
+
+/** The most recent voice call context for a phone number. */
+interface VoiceCallContext {
+    /** Timestamp (RFC3339) when the call was received by the AI voice agent. */
+    started_at: string;
+    summary?: string;
+    transcript?: string;
+    handoff_reason?: string;
+    last_executed_procedure?: string;
+    last_executed_procedure_url?: string;
+    gradient_labs_url?: string;
+}
+interface ReadVoiceCallContextParams {
+    /** Time window (seconds) to look back for recent call events. Default 60, min 5. */
+    lookback_seconds?: number;
+    /** Include large fields (full transcript and untruncated summary). */
+    include_large_fields?: boolean;
+}
+
+/**
+ * Voice endpoints. Requires an Integration API key.
+ */
+declare class Voice {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Retrieves the most recent call context for a given phone number. Throws an
+     * {@link ApiError} with status 404 if there have been no recent call events.
+     */
+    getLatestCallContext(phoneNumber: string, params?: ReadVoiceCallContextParams, config?: RequestConfig): Promise<VoiceCallContext>;
+}
+
+/**
+ * Well-known error codes returned by the Gradient Labs API in the `code` field
+ * of an error response. Callers can switch on {@link ApiError.code} rather than
+ * comparing message strings.
+ *
+ * The union is intentionally open (`| (string & {})`) so that a future
+ * server-side code never breaks a consumer at compile time.
+ */
+declare const ErrorCode: {
+    readonly NotFound: "not_found";
+    readonly Unauthenticated: "unauthenticated";
+    readonly PermissionDenied: "permission_denied";
+    readonly InvalidArgument: "invalid_argument";
+    readonly FailedPrecondition: "failed_precondition";
+    readonly ResourceExhausted: "resource_exhausted";
+    readonly AlreadyExists: "already_exists";
+    readonly Unavailable: "unavailable";
+    readonly DeadlineExceeded: "deadline_exceeded";
+    readonly Internal: "internal";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode] | (string & {});
+/**
+ * Base class for every error thrown by this client. Catch this to handle any
+ * failure originating from the library.
+ */
+declare class GradientLabsError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when the client is misconfigured (e.g. a missing API key). These are
+ * raised before any network request is made.
+ */
+declare class ConfigurationError extends GradientLabsError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the API returns a non-2xx response. It carries the HTTP status
+ * code along with the parsed error envelope (`code`, `message`, `details`).
+ */
+declare class ApiError extends GradientLabsError {
+    /** HTTP status code of the response. */
+    readonly statusCode: number;
+    /** Machine-readable error code from the response envelope. */
+    readonly code: ErrorCode;
+    /** Arbitrary structured details returned with the error. */
+    readonly details: Record<string, unknown>;
+    constructor(args: {
+        statusCode: number;
+        code: ErrorCode;
+        message: string;
+        details?: Record<string, unknown>;
+    });
+    /**
+     * The identifier that can be given to Gradient Labs technical support to
+     * investigate an error, if present in the error details.
+     */
+    get traceId(): string | undefined;
+}
+
+/** The set of webhook event types currently delivered by Gradient Labs. */
+declare const WebhookType: {
+    readonly AgentMessage: "agent.message";
+    readonly ConversationHandOff: "conversation.hand_off";
+    readonly ConversationFinished: "conversation.finished";
+    readonly ActionExecute: "action.execute";
+    readonly ResourcePull: "resource.pull";
+    readonly BackOfficeTaskComplete: "back-office-task.complete";
+    readonly BackOfficeTaskHandOff: "back-office-task.hand-off";
+    readonly BackOfficeTaskFail: "back-office-task.fail";
+};
+type WebhookType = (typeof WebhookType)[keyof typeof WebhookType];
+/**
+ * The conversation an `agent.message`, `conversation.hand_off`, or
+ * `conversation.finished` event relates to.
+ */
+interface WebhookConversation {
+    id: string;
+    customer_id: string;
+}
+/**
+ * The conversation an `action.execute` or `resource.pull` event relates to.
+ * Present only when the action ran in a conversation context.
+ */
+interface ActionWebhookConversation {
+    id: string;
+    customer_id: string;
+    customer_source: CustomerSource;
+    /** Metadata attached to the conversation when it was started. */
+    metadata: unknown;
+}
+/**
+ * The back-office task an `action.execute` or `resource.pull` event relates to.
+ * Present only when the action ran in a back-office task context.
+ */
+interface ActionWebhookBackOfficeTask {
+    id: string;
+}
+interface AgentMessageEvent {
+    conversation: WebhookConversation;
+    body: string;
+    total?: number;
+    sequence?: number;
+    intent?: string;
+    /** Whether this is a holding response sent while the agent works. */
+    is_holding?: boolean;
+    /** External ID of the customer message this turn is responding to. */
+    last_customer_message_id?: string;
+}
+interface ConversationHandOffEvent {
+    conversation: WebhookConversation;
+    target?: string;
+    /** Coded reason the agent wants to hand off. */
+    reason_code: string;
+    /** Human-legible description of the reason code. */
+    reason: string;
+    note?: string;
+    intent?: string;
+}
+interface ConversationFinishedEvent {
+    conversation: WebhookConversation;
+    reason_code?: string;
+    intent?: string;
+}
+interface ActionExecuteEvent {
+    action: string;
+    /** Arguments to execute the action with. */
+    params: unknown;
+    /** Set when the action ran in a conversation context. */
+    conversation?: ActionWebhookConversation;
+    /** Set when the action ran in a back-office task context. */
+    back_office_task?: ActionWebhookBackOfficeTask;
+}
+interface ResourcePullEvent {
+    resource_type: string;
+    /** Set when the pull ran in a conversation context. */
+    conversation?: ActionWebhookConversation;
+    /** Set when the pull ran in a back-office task context. */
+    back_office_task?: ActionWebhookBackOfficeTask;
+}
+/**
+ * The three back-office task events all carry the full task under a single
+ * `back_office_task` key. The outcome (result / failure reasons / hand-off
+ * reason) lives inside that task object.
+ */
+interface BackOfficeTaskCompleteEvent {
+    back_office_task: BackOfficeTask;
+}
+interface BackOfficeTaskHandOffEvent {
+    back_office_task: BackOfficeTask;
+}
+interface BackOfficeTaskFailEvent {
+    back_office_task: BackOfficeTask;
+}
+/** Fields common to every webhook envelope. */
+interface WebhookBase {
+    id: string;
+    sequence_number: number;
+    /** RFC3339 timestamp of when the event was generated. */
+    timestamp: string;
+}
+/**
+ * A parsed, verified webhook event. Discriminate on `type` for exhaustive,
+ * type-safe handling of the `data` payload.
+ */
+type WebhookEvent = (WebhookBase & {
+    type: "agent.message";
+    data: AgentMessageEvent;
+}) | (WebhookBase & {
+    type: "conversation.hand_off";
+    data: ConversationHandOffEvent;
+}) | (WebhookBase & {
+    type: "conversation.finished";
+    data: ConversationFinishedEvent;
+}) | (WebhookBase & {
+    type: "action.execute";
+    data: ActionExecuteEvent;
+}) | (WebhookBase & {
+    type: "resource.pull";
+    data: ResourcePullEvent;
+}) | (WebhookBase & {
+    type: "back-office-task.complete";
+    data: BackOfficeTaskCompleteEvent;
+}) | (WebhookBase & {
+    type: "back-office-task.hand-off";
+    data: BackOfficeTaskHandOffEvent;
+}) | (WebhookBase & {
+    type: "back-office-task.fail";
+    data: BackOfficeTaskFailEvent;
+});
+/** The result of parsing a webhook request. */
+interface ParsedWebhook {
+    event: WebhookEvent;
+    /**
+     * The optional sensitive conversation token from the `X-GradientLabs-Token`
+     * header, if present.
+     */
+    token?: string;
+}
+
+/** Thrown when a webhook's signature or timestamp cannot be verified. Respond 401. */
+declare class InvalidWebhookSignatureError extends GradientLabsError {
+    constructor(message?: string);
+}
+/** Thrown when a webhook of an unrecognised type is received. Log it and respond 200. */
+declare class UnknownWebhookTypeError extends GradientLabsError {
+    readonly type: string;
+    constructor(type: string);
+}
+/** A source of request headers: a Fetch `Headers`, a Node headers object, or a plain map. */
+type HeadersLike = {
+    get(name: string): string | null;
+} | Record<string, string | string[] | undefined>;
+/** The raw request body. Signatures are computed over the exact bytes received. */
+type WebhookBody = string | Uint8Array;
+interface WebhookVerifierConfig {
+    /** The webhook signing key configured for your workspace. */
+    signingKey: string;
+    /** Maximum accepted age of a webhook, in milliseconds. Defaults to 5 minutes. */
+    leewayMs?: number;
+    /** Injectable clock for testing. Defaults to Date.now. */
+    now?: () => number;
+}
+/**
+ * Verifies the authenticity of requests to your webhook endpoint using the
+ * `X-GradientLabs-Signature` header (format `t=<unix_ts>,v1=<hex>`).
+ */
+declare class WebhookVerifier {
+    private readonly signingKey;
+    private readonly leewayMs;
+    private readonly now;
+    constructor(config: WebhookVerifierConfig);
+    /**
+     * Verifies a webhook's signature and timestamp. Throws
+     * {@link InvalidWebhookSignatureError} if verification fails.
+     */
+    verify(args: {
+        body: WebhookBody;
+        signature: string | null | undefined;
+    }): void;
+    /**
+     * Verifies a webhook request, then parses it into a typed event. Returns the
+     * event along with the optional `X-GradientLabs-Token` passthrough.
+     *
+     * Verification always happens before the event type is inspected.
+     */
+    parse(args: {
+        body: WebhookBody;
+        headers: HeadersLike;
+    }): ParsedWebhook;
+    private computeSignature;
+}
+
+interface GradientLabsConfig {
+    /** Your Gradient Labs API key. Required. */
+    apiKey: string;
+    /** Override the base URL. Defaults to https://api.gradient-labs.ai. */
+    baseUrl?: string;
+    /** The webhook signing key, required to verify incoming webhooks. */
+    webhookSigningKey?: string;
+    /** Maximum accepted age of a webhook, in milliseconds. Defaults to 5 minutes. */
+    webhookLeewayMs?: number;
+    /** Inject a custom fetch implementation (tests, proxies, instrumentation). */
+    fetch?: FetchLike;
+    /** Per-request timeout in milliseconds. No timeout by default. */
+    timeoutMs?: number;
+}
+/**
+ * The Gradient Labs API client. Construct one with your API key, then access
+ * endpoints through the resource namespaces (e.g. `client.conversations.start`).
+ */
+declare class GradientLabs {
+    readonly conversations: Conversations;
+    readonly outboundConversations: OutboundConversations;
+    readonly backOfficeTasks: BackOfficeTasks;
+    readonly voice: Voice;
+    readonly tools: Tools;
+    readonly articles: Articles;
+    readonly topics: Topics;
+    readonly procedures: Procedures;
+    readonly handOffTargets: HandOffTargets;
+    readonly resourceSources: ResourceSources;
+    readonly resourceTypes: ResourceTypes;
+    readonly secrets: Secrets;
+    readonly notes: Notes;
+    readonly terminologySubstitutions: TerminologySubstitutions;
+    readonly trafficGroups: TrafficGroups;
+    readonly ipAddresses: IpAddressesResource;
+    private readonly webhookVerifier?;
+    constructor(config: GradientLabsConfig);
+    /**
+     * The webhook verifier. Throws {@link ConfigurationError} if the client was
+     * created without a `webhookSigningKey`.
+     */
+    get webhooks(): WebhookVerifier;
+}
+
+export { type ActionExecuteEvent, type ActionWebhookBackOfficeTask, type ActionWebhookConversation, type AddMessageParams, type AgentMessageEvent, type AgentMetadata, ApiError, ArticleStatus, ArticleUsageStatus, ArticleVisibility, Articles, type AssignConversationParams, type AsyncDefinition, type Attachment, AttachmentType, type Attribute, AttributeCardinality, AttributeType, type BackOfficeTask, type BackOfficeTaskAttachment, type BackOfficeTaskAttachmentInput, type BackOfficeTaskCompleteEvent, type BackOfficeTaskFailEvent, type BackOfficeTaskHandOffEvent, type BackOfficeTaskResult, BackOfficeTaskResultType, BackOfficeTaskStatus, BackOfficeTasks, BodyEncoding, type CancelConversationParams, Channel, type ChildTool, ConfigurationError, type Conversation, type ConversationEventParams, ConversationEventType, type ConversationFinishedEvent, type ConversationHandOffEvent, Conversations, type CreateBackOfficeTaskParams, type CreateNoteParams, type CreateResourceSourceParams, type CreateResourceTypeParams, type CreateTerminologySubstitutionParams, type CreateToolParams, type CreateTrafficGroupParams, CustomerSource, type DeleteHandOffTargetParams, ErrorCode, type ExecuteToolParams, type FetchLike, type FinishConversationParams, type GatedConfig, type GetDefaultHandOffTargetParams, GradientLabs, type GradientLabsConfig, GradientLabsError, type HandOffTarget, HandOffTargets, type HeadersLike, type HttpBodyDefinition, type HttpDefinition, InvalidWebhookSignatureError, type IpAddresses, IpAddressesResource, type ListProceduresParams, type ListTopicsParams, type McpConfiguration, type Message, type Note, NoteStatus, Notes, type OutboundConversation, OutboundConversations, type Page, type PageInfo, type ParameterOption, ParameterSource, ParameterType, type ParsedWebhook, ParticipantType, type Procedure, ProcedureStatus, type ProcedureVersion, Procedures, type RateConversationParams, type ReadConversationParams, type ReadToolParams, type ReadTopicParams, type ReadVoiceCallContextParams, type RefreshMechanismHttp, type RequestConfig, type ResourcePullEvent, type ResourceSource, type ResourceSourceHttpBodyDefinition, type ResourceSourceHttpConfig, ResourceSourceRefreshStrategy, ResourceSourceScope, ResourceSourceType, type ResourceSourceWebhookConfig, ResourceSources, type ResourceType, ResourceTypeRefreshStrategy, ResourceTypeScope, ResourceTypes, type ResumeConversationParams, type ReturnAsyncToolResultParams, type Schema, SchemaUpdateStrategy, type Secret, Secrets, type SetArticleUsageStatusParams, type SetDefaultHandOffTargetParams, type SetGatedVersionParams, type SetNoteStatusParams, type SetProcedureLimitParams, type SourceConfig, type StartConversationParams, type StartOutboundConversationParams, SupportPlatform, type TerminologySubstitution, TerminologySubstitutions, type Tool, type ToolArgument, type ToolExecutionResult, type ToolParameter, type ToolParameterSet, type ToolWebhookConfiguration, Tools, type Topic, Topics, type TrafficGroup, type TrafficGroupTarget, type TrafficGroupTargetParams, TrafficGroups, UnknownWebhookTypeError, type UpdateNoteParams, type UpdateResourceSourceParams, type UpdateResourceTypeParams, type UpdateSchemaByExamplesParams, type UpdateTerminologySubstitutionParams, type UpdateToolParams, type UpdateTrafficGroupParams, type UpsertArticleParams, type UpsertHandOffTargetParams, type UpsertTopicParams, type UserDetails, Voice, type VoiceCallContext, type WebhookBody, type WebhookConversation, type WebhookEvent, WebhookType, WebhookVerifier, type WebhookVerifierConfig, type WorkflowConfiguration, type WriteSecretParams };