@roarkanalytics/sdk 3.21.0 → 4.1.0

package/resources/agent-config.d.mts

@@ -0,0 +1,394 @@
+import { APIResource } from "../core/resource.mjs";
+import * as AgentConfigAPI from "./agent-config.mjs";
+import { APIPromise } from "../core/api-promise.mjs";
+import { RequestOptions } from "../internal/request-options.mjs";
+export declare class AgentConfig extends APIResource {
+    /**
+     * Write a new revision onto a channel. Writing production creates the key when it
+     * does not exist; writing staging stages a candidate that only Roark-recognized
+     * simulation sessions will read. Every write is a new revision; nothing is
+     * overwritten.
+     *
+     * @example
+     * ```ts
+     * const agentConfig = await client.agentConfig.update('x', {
+     *   channel: 'production',
+     *   document: { foo: 'string' },
+     * });
+     * ```
+     */
+    update(key: string, body: AgentConfigUpdateParams, options?: RequestOptions): APIPromise<AgentConfigUpdateResponse>;
+    /**
+     * List the managed agent configs in this project, most recent first.
+     *
+     * @example
+     * ```ts
+     * const agentConfigs = await client.agentConfig.list();
+     * ```
+     */
+    list(options?: RequestOptions): APIPromise<AgentConfigListResponse>;
+    /**
+     * Clear the staging channel. Production is untouched; recognized simulation
+     * sessions go back to reading production.
+     *
+     * @example
+     * ```ts
+     * const response =
+     *   await client.agentConfig.deleteStaging('x');
+     * ```
+     */
+    deleteStaging(key: string, options?: RequestOptions): APIPromise<AgentConfigDeleteStagingResponse>;
+    /**
+     * Fetch one managed config with its channel pointers and recent revisions, newest
+     * first.
+     *
+     * @example
+     * ```ts
+     * const response = await client.agentConfig.getByID('x');
+     * ```
+     */
+    getByID(key: string, options?: RequestOptions): APIPromise<AgentConfigGetByIDResponse>;
+    /**
+     * Point the production channel at the staging revision. Real traffic reads it from
+     * the next session onward; roll back by writing the prior revision id to
+     * production (the chain preserves every state).
+     *
+     * @example
+     * ```ts
+     * const response = await client.agentConfig.promote('x');
+     * ```
+     */
+    promote(key: string, options?: RequestOptions): APIPromise<AgentConfigPromoteResponse>;
+    /**
+     * The call your agent makes at session start. Returns the config JSON for this
+     * session, with per-session simulation recognition built in: when the session was
+     * originated by a Roark simulation (matched by caller number against the calls
+     * Roark has in flight), the STAGING revision is served for that session only, so
+     * Autoimprove candidates are tested on your real deployment. Real traffic always
+     * resolves to production; any recognition miss degrades to production too.
+     *
+     * On the first fetch of an unknown key, pass `defaults` (your baked-in config):
+     * the key is registered and the defaults become revision 1. That makes integration
+     * a single call.
+     *
+     * Cache the response per session; do not fetch per turn.
+     *
+     * @example
+     * ```ts
+     * const response = await client.agentConfig.resolve('x');
+     * ```
+     */
+    resolve(key: string, body?: AgentConfigResolveParams | null | undefined, options?: RequestOptions): APIPromise<AgentConfigResolveResponse>;
+}
+export interface ManagedAgentConfigRevision {
+    id: string;
+    /**
+     * ISO 8601.
+     */
+    createdAt: string;
+    /**
+     * Who wrote it: your own pushes, or the Autoimprove loop staging a candidate.
+     */
+    createdByType: 'CUSTOMER' | 'AUTOIMPROVE';
+    /**
+     * The config JSON, verbatim.
+     */
+    document: {
+        [key: string]: unknown;
+    };
+    parentRevisionId: string | null;
+    /**
+     * One-line story of the change.
+     */
+    summary: string | null;
+}
+export interface AgentConfigUpdateResponse {
+    /**
+     * A managed config for a code-first agent (LiveKit, Pipecat, or any stack using
+     * the SDK): your agent fetches its tunable surface from Roark at session start.
+     * Two channels: production for real traffic, staging for candidates under test.
+     */
+    data: AgentConfigUpdateResponse.Data;
+}
+export declare namespace AgentConfigUpdateResponse {
+    /**
+     * A managed config for a code-first agent (LiveKit, Pipecat, or any stack using
+     * the SDK): your agent fetches its tunable surface from Roark at session start.
+     * Two channels: production for real traffic, staging for candidates under test.
+     */
+    interface Data {
+        id: string;
+        /**
+         * The linked Roark agent, when one exists.
+         */
+        agentId: string | null;
+        /**
+         * ISO 8601.
+         */
+        createdAt: string;
+        /**
+         * The stable handle your code fetches by.
+         */
+        key: string;
+        /**
+         * The revision real traffic reads.
+         */
+        productionRevisionId: string | null;
+        /**
+         * The candidate revision Roark test calls read. Null when nothing is staged.
+         */
+        stagingRevisionId: string | null;
+        /**
+         * ISO 8601.
+         */
+        updatedAt: string;
+    }
+}
+export interface AgentConfigListResponse {
+    data: Array<AgentConfigListResponse.Data>;
+}
+export declare namespace AgentConfigListResponse {
+    /**
+     * A managed config for a code-first agent (LiveKit, Pipecat, or any stack using
+     * the SDK): your agent fetches its tunable surface from Roark at session start.
+     * Two channels: production for real traffic, staging for candidates under test.
+     */
+    interface Data {
+        id: string;
+        /**
+         * The linked Roark agent, when one exists.
+         */
+        agentId: string | null;
+        /**
+         * ISO 8601.
+         */
+        createdAt: string;
+        /**
+         * The stable handle your code fetches by.
+         */
+        key: string;
+        /**
+         * The revision real traffic reads.
+         */
+        productionRevisionId: string | null;
+        /**
+         * The candidate revision Roark test calls read. Null when nothing is staged.
+         */
+        stagingRevisionId: string | null;
+        /**
+         * ISO 8601.
+         */
+        updatedAt: string;
+    }
+}
+export interface AgentConfigDeleteStagingResponse {
+    /**
+     * A managed config for a code-first agent (LiveKit, Pipecat, or any stack using
+     * the SDK): your agent fetches its tunable surface from Roark at session start.
+     * Two channels: production for real traffic, staging for candidates under test.
+     */
+    data: AgentConfigDeleteStagingResponse.Data;
+}
+export declare namespace AgentConfigDeleteStagingResponse {
+    /**
+     * A managed config for a code-first agent (LiveKit, Pipecat, or any stack using
+     * the SDK): your agent fetches its tunable surface from Roark at session start.
+     * Two channels: production for real traffic, staging for candidates under test.
+     */
+    interface Data {
+        id: string;
+        /**
+         * The linked Roark agent, when one exists.
+         */
+        agentId: string | null;
+        /**
+         * ISO 8601.
+         */
+        createdAt: string;
+        /**
+         * The stable handle your code fetches by.
+         */
+        key: string;
+        /**
+         * The revision real traffic reads.
+         */
+        productionRevisionId: string | null;
+        /**
+         * The candidate revision Roark test calls read. Null when nothing is staged.
+         */
+        stagingRevisionId: string | null;
+        /**
+         * ISO 8601.
+         */
+        updatedAt: string;
+    }
+}
+export interface AgentConfigGetByIDResponse {
+    data: AgentConfigGetByIDResponse.Data;
+}
+export declare namespace AgentConfigGetByIDResponse {
+    /**
+     * A managed config for a code-first agent (LiveKit, Pipecat, or any stack using
+     * the SDK): your agent fetches its tunable surface from Roark at session start.
+     * Two channels: production for real traffic, staging for candidates under test.
+     */
+    interface Data {
+        id: string;
+        /**
+         * The linked Roark agent, when one exists.
+         */
+        agentId: string | null;
+        /**
+         * ISO 8601.
+         */
+        createdAt: string;
+        /**
+         * The stable handle your code fetches by.
+         */
+        key: string;
+        /**
+         * The revision real traffic reads.
+         */
+        productionRevisionId: string | null;
+        /**
+         * Recent revisions, newest first.
+         */
+        revisions: Array<AgentConfigAPI.ManagedAgentConfigRevision>;
+        /**
+         * The candidate revision Roark test calls read. Null when nothing is staged.
+         */
+        stagingRevisionId: string | null;
+        /**
+         * ISO 8601.
+         */
+        updatedAt: string;
+    }
+}
+export interface AgentConfigPromoteResponse {
+    /**
+     * A managed config for a code-first agent (LiveKit, Pipecat, or any stack using
+     * the SDK): your agent fetches its tunable surface from Roark at session start.
+     * Two channels: production for real traffic, staging for candidates under test.
+     */
+    data: AgentConfigPromoteResponse.Data;
+}
+export declare namespace AgentConfigPromoteResponse {
+    /**
+     * A managed config for a code-first agent (LiveKit, Pipecat, or any stack using
+     * the SDK): your agent fetches its tunable surface from Roark at session start.
+     * Two channels: production for real traffic, staging for candidates under test.
+     */
+    interface Data {
+        id: string;
+        /**
+         * The linked Roark agent, when one exists.
+         */
+        agentId: string | null;
+        /**
+         * ISO 8601.
+         */
+        createdAt: string;
+        /**
+         * The stable handle your code fetches by.
+         */
+        key: string;
+        /**
+         * The revision real traffic reads.
+         */
+        productionRevisionId: string | null;
+        /**
+         * The candidate revision Roark test calls read. Null when nothing is staged.
+         */
+        stagingRevisionId: string | null;
+        /**
+         * ISO 8601.
+         */
+        updatedAt: string;
+    }
+}
+export interface AgentConfigResolveResponse {
+    data: AgentConfigResolveResponse.Data;
+}
+export declare namespace AgentConfigResolveResponse {
+    interface Data {
+        /**
+         * Which channel this session resolved to.
+         */
+        channel: 'production' | 'staging';
+        /**
+         * The config JSON to apply.
+         */
+        document: {
+            [key: string]: unknown;
+        };
+        key: string;
+        revisionId: string;
+        /**
+         * Set when this session is a Roark simulation call. Stamp it (and the revisionId)
+         * into your session metadata so analysis attributes the call correctly.
+         */
+        simulationJobId: string | null;
+    }
+}
+export interface AgentConfigUpdateParams {
+    /**
+     * Which channel to write.
+     */
+    channel: 'production' | 'staging';
+    /**
+     * The full config JSON for the new revision.
+     */
+    document: {
+        [key: string]: unknown;
+    };
+    /**
+     * Link this config to a Roark agent (the one your calls report). Required before
+     * Autoimprove can run on it: the link is how a fix finds the config channel.
+     */
+    agentId?: string;
+    /**
+     * One-line story of the change.
+     */
+    summary?: string;
+}
+export interface AgentConfigResolveParams {
+    /**
+     * Your baked-in config. On the first fetch of an unknown key this registers the
+     * config and becomes revision 1, so integration is a single call. Ignored once the
+     * key exists.
+     */
+    defaults?: {
+        [key: string]: unknown;
+    };
+    /**
+     * Session context. When the call was originated by a Roark simulation, Roark
+     * recognizes it here and serves the staging revision for this session only; real
+     * traffic always gets production.
+     */
+    session?: AgentConfigResolveParams.Session;
+}
+export declare namespace AgentConfigResolveParams {
+    /**
+     * Session context. When the call was originated by a Roark simulation, Roark
+     * recognizes it here and serves the staging revision for this session only; real
+     * traffic always gets production.
+     */
+    interface Session {
+        /**
+         * The number your agent was reached on (E.164).
+         */
+        calledNumber?: string;
+        /**
+         * The number calling your agent (E.164). Required for simulation recognition.
+         */
+        callerNumber?: string;
+        /**
+         * Your session or room identifier, for correlation.
+         */
+        sessionId?: string;
+    }
+}
+export declare namespace AgentConfig {
+    export { type ManagedAgentConfigRevision as ManagedAgentConfigRevision, type AgentConfigUpdateResponse as AgentConfigUpdateResponse, type AgentConfigListResponse as AgentConfigListResponse, type AgentConfigDeleteStagingResponse as AgentConfigDeleteStagingResponse, type AgentConfigGetByIDResponse as AgentConfigGetByIDResponse, type AgentConfigPromoteResponse as AgentConfigPromoteResponse, type AgentConfigResolveResponse as AgentConfigResolveResponse, type AgentConfigUpdateParams as AgentConfigUpdateParams, type AgentConfigResolveParams as AgentConfigResolveParams, };
+}
+//# sourceMappingURL=agent-config.d.mts.map

package/resources/agent-config.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config.d.mts","sourceRoot":"","sources":["../src/resources/agent-config.ts"],"names":[],"mappings":"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"}