@firststep-studio/sdk 0.9.0 → 0.11.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-GoTI_c14.mjs';
-export { O as AnalyticsContext, E as ChatbotInfo, F as ClassifierConfig, D as DeploymentInfo, G as FormData, V as FormFieldDefinition, W as FormFieldType, J as FormFieldValue, U as FormSchema, n as HandlerInfo, _ as HandoffContext, f as HandoffInboundContext, $ as HandoffOptions, x as Helpline, w as HelplineResult, v as HelplineSearchOptions, I as IntegrationContext, u as IntegrationResult, Q as InteractionEvent, T as InteractionEventType, t as KnowledgeColumnMetadata, K as KnowledgeContext, s as KnowledgeMetadata, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, X as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, B as RoutingDecision, M as RoutingLog, Y as SchemaAgent, Z as SchemaQuestion, p as SessionContext, N as SessionMetadata, q as SessionState, e as SessionStatus, y as StorageContext, z as StorageSetOptions } from './types-GoTI_c14.mjs';
+import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-DYJ44S2E.mjs';
+export { O as AnalyticsContext, E as ChatbotInfo, F as ClassifierConfig, D as DeploymentInfo, G as FormData, V as FormFieldDefinition, W as FormFieldType, J as FormFieldValue, U as FormSchema, n as HandlerInfo, _ as HandoffContext, f as HandoffInboundContext, $ as HandoffOptions, x as Helpline, w as HelplineResult, v as HelplineSearchOptions, I as IntegrationContext, u as IntegrationResult, Q as InteractionEvent, T as InteractionEventType, t as KnowledgeColumnMetadata, K as KnowledgeContext, s as KnowledgeMetadata, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, X as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, B as RoutingDecision, M as RoutingLog, Y as SchemaAgent, Z as SchemaQuestion, p as SessionContext, N as SessionMetadata, q as SessionState, e as SessionStatus, y as StorageContext, z as StorageSetOptions } from './types-DYJ44S2E.mjs';
 
 /**
  * UCP (Universal Classification Protocol) Types
@@ -680,6 +680,14 @@ interface PlatformKnowledgeSummary {
     type?: string;
     /** Owning organization ID */
     organizationId: string;
+    /**
+     * True for handler-managed documents created through the protocol
+     * write API. System-owned knowledge is hidden from every Studio UI
+     * surface and only appears in `list` when `includeSystemOwned` is set.
+     */
+    isSystemOwned?: boolean;
+    /** Whether semantic search (record embedding) is enabled. */
+    ragEnabled?: boolean;
     /** Timestamps */
     createdAt?: number | string;
     updatedAt?: number | string;
@@ -698,7 +706,74 @@ interface ListKnowledgeOptions {
      * `publicReadable` in Studio).
      */
     orgId?: string;
+    /**
+     * Include system-owned (handler-managed) knowledge in the listing.
+     * Only honored when listing the token's own org; other orgs never
+     * expose their system-owned documents.
+     */
+    includeSystemOwned?: boolean;
 }
+/** Sheet definition for `knowledge.create`. */
+interface CreateKnowledgeSheet {
+    /** Stable sheet id, referenced later by record writes and search. */
+    id: string;
+    name: string;
+    description?: string;
+    /**
+     * Column definitions ({ id, name, type, ... }). Loose-typed; the
+     * Studio schema validates `type` against its column-type enum.
+     */
+    columns?: Array<Record<string, unknown>>;
+}
+interface CreateKnowledgeOptions {
+    description?: string;
+    /**
+     * Enable semantic search at creation time. Defaults to false; can be
+     * flipped later with `setRagEnabled` (which also backfills embeddings
+     * for records inserted while the flag was off).
+     */
+    ragEnabled?: boolean;
+}
+/** A raw record as returned by the protocol record-write endpoints. */
+interface PlatformKnowledgeRecord {
+    id: string;
+    knowledgeId: string;
+    sheetId: string;
+    data: Record<string, unknown>;
+    createdAt?: number | string;
+    updatedAt?: number | string;
+}
+interface KnowledgeSearchOptions {
+    /** Max records to return (server-side clamped to 1..50, default 10). */
+    limit?: number;
+    /**
+     * Optional sheet filter. Pass a sheet id (from the knowledge document)
+     * to restrict the search to that sheet. Omit to search across all
+     * sheets in the knowledge.
+     */
+    sheetId?: string;
+}
+/**
+ * A single hit from `client.knowledge.search`. `score` is the Atlas
+ * vector similarity score (cosine in our setup, so higher is closer).
+ * `data` mirrors the underlying record fields (column id -> value).
+ */
+interface PlatformKnowledgeSearchHit {
+    id: string;
+    knowledgeId: string;
+    sheetId: string;
+    data: Record<string, unknown>;
+    score: number;
+    createdAt?: number | string;
+    updatedAt?: number | string;
+}
+/**
+ * Helplines query params — passed verbatim to Throughline. Loose-typed
+ * so the SDK stays compatible with new Throughline query keys without
+ * a release. Required by Throughline today: `country_code`. Common
+ * optional keys: `topic`, `contact_method`, `limit`.
+ */
+type ThroughlineHelplinesQuery = Record<string, string | number | boolean | undefined>;
 declare class PlatformError extends Error {
     status: number;
     constructor(message: string, status: number);
@@ -738,8 +813,12 @@ declare class PlatformClient {
      *
      * Reads are allowed when the SDK token's org matches the target org,
      * OR when the target org has `publicReadable: true` on the Studio side.
-     * Writes are not yet exposed here — those still go through the user-
-     * authenticated /api/knowledge routes from the Studio UI.
+     *
+     * Writes target system-owned (handler-managed) knowledge only: the
+     * protocol API stamps everything created here `isSystemOwned: true`,
+     * which keeps it out of every Studio UI surface — Studio acts as a
+     * plain storage + RAG layer for it. UI-managed knowledge cannot be
+     * modified through this surface.
      */
     knowledge: {
         /**
@@ -753,6 +832,108 @@ declare class PlatformClient {
          * publicReadable).
          */
         get: (id: string) => Promise<PlatformKnowledge>;
+        /**
+         * Semantic search over a knowledge's records. Studio embeds the
+         * query server-side (Gemini gemini-embedding-001) and runs Atlas
+         * Vector Search against the `vector_index` on `knowledge_records`.
+         *
+         * Same read access rules as `get` — same-org or publicReadable.
+         *
+         * Returns an empty array (not an error) when the Atlas index is
+         * absent or when nothing matches, so handler code can treat
+         * "no hits" and "RAG not configured yet" identically.
+         */
+        search: (id: string, query: string, options?: KnowledgeSearchOptions) => Promise<PlatformKnowledgeSearchHit[]>;
+        /**
+         * Turn semantic search on or off for a knowledge.
+         *
+         * Writes are strictly same-org — `publicReadable` does NOT confer
+         * write access. Flipping `false -> true` schedules a background
+         * backfill of existing records on the Studio side; this call
+         * returns as soon as the flag is persisted, not when the backfill
+         * finishes.
+         *
+         * Idempotent: setting the flag to its current value is a no-op
+         * (`backfillTriggered` will be `false`).
+         */
+        setRagEnabled: (id: string, enabled: boolean) => Promise<{
+            id: string;
+            ragEnabled: boolean;
+            backfillTriggered: boolean;
+        }>;
+        /**
+         * Create a system-owned database knowledge under the token's org.
+         *
+         * 409 (surfaced as an error) means a knowledge of the same name
+         * already exists in the org. Idempotent callers should recover by
+         * listing with `includeSystemOwned: true` and matching on name.
+         */
+        create: (name: string, sheets: CreateKnowledgeSheet[], options?: CreateKnowledgeOptions) => Promise<PlatformKnowledge>;
+        /**
+         * Delete a system-owned knowledge and all of its records.
+         * Refused (403) for UI-managed knowledge.
+         */
+        delete: (id: string) => Promise<{
+            deletedRecords: number;
+        }>;
+        /**
+         * Append one record to a sheet. Embeds async when ragEnabled.
+         */
+        addRecord: (id: string, sheetId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
+        /**
+         * Replace a record's data payload. Re-embeds async when ragEnabled.
+         */
+        updateRecord: (id: string, recordId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
+        /** Delete one record. */
+        deleteRecord: (id: string, recordId: string) => Promise<void>;
+        /**
+         * Bulk-insert records into one sheet (each array entry becomes one
+         * record's `data`). With `replace: true` the sheet's existing
+         * records are deleted first — the full-resync primitive backfills
+         * use. Server caps a single call at 5000 records.
+         */
+        bulkRecords: (id: string, sheetId: string, records: Array<Record<string, unknown>>, options?: {
+            replace?: boolean;
+        }) => Promise<{
+            insertedCount: number;
+            deletedCount: number;
+        }>;
+    };
+    /**
+     * Throughline (find-a-helpline) surface.
+     *
+     * Handlers used to call api.throughlinecare.com directly, which meant
+     * each handler had to hold OAuth client credentials and re-implement
+     * token caching. Studio holds the per-org credentials on
+     * `Organization.throughline.{clientId,clientSecret}` and proxies the
+     * Throughline endpoints; the SDK token identifies the org server-side
+     * so callers never see the secret.
+     *
+     * Responses are returned as parsed JSON. Studio does not reshape the
+     * Throughline body — these surfaces stay compatible with future
+     * Throughline API additions without a Studio or SDK release.
+     *
+     * Caching (24h on countries + topics, none on helplines) is server-
+     * side; the SDK is stateless.
+     */
+    throughline: {
+        /**
+         * GET /v1/countries — Throughline's country catalog (codes,
+         * names, emergency numbers). Cached 24h server-side.
+         */
+        getCountries: () => Promise<unknown>;
+        /**
+         * GET /v1/topics — Throughline's topic taxonomy used to filter
+         * helpline searches. Cached 24h server-side.
+         */
+        getTopics: () => Promise<unknown>;
+        /**
+         * GET /v1/helplines?country_code=...&topic=...&... — live search,
+         * not cached. The query object is forwarded verbatim to Throughline,
+         * so any new key Throughline adds will work without an SDK change.
+         * Required by Throughline today: `country_code`.
+         */
+        getHelplines: (query: ThroughlineHelplinesQuery) => Promise<unknown>;
     };
 }
 /**
@@ -1027,4 +1208,4 @@ declare class LLMClient {
  */
 declare function createLLMClient(config: LLMClientConfig): LLMClient;
 
-export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };
+export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-GoTI_c14.js';
-export { O as AnalyticsContext, E as ChatbotInfo, F as ClassifierConfig, D as DeploymentInfo, G as FormData, V as FormFieldDefinition, W as FormFieldType, J as FormFieldValue, U as FormSchema, n as HandlerInfo, _ as HandoffContext, f as HandoffInboundContext, $ as HandoffOptions, x as Helpline, w as HelplineResult, v as HelplineSearchOptions, I as IntegrationContext, u as IntegrationResult, Q as InteractionEvent, T as InteractionEventType, t as KnowledgeColumnMetadata, K as KnowledgeContext, s as KnowledgeMetadata, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, X as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, B as RoutingDecision, M as RoutingLog, Y as SchemaAgent, Z as SchemaQuestion, p as SessionContext, N as SessionMetadata, q as SessionState, e as SessionStatus, y as StorageContext, z as StorageSetOptions } from './types-GoTI_c14.js';
+import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-DYJ44S2E.js';
+export { O as AnalyticsContext, E as ChatbotInfo, F as ClassifierConfig, D as DeploymentInfo, G as FormData, V as FormFieldDefinition, W as FormFieldType, J as FormFieldValue, U as FormSchema, n as HandlerInfo, _ as HandoffContext, f as HandoffInboundContext, $ as HandoffOptions, x as Helpline, w as HelplineResult, v as HelplineSearchOptions, I as IntegrationContext, u as IntegrationResult, Q as InteractionEvent, T as InteractionEventType, t as KnowledgeColumnMetadata, K as KnowledgeContext, s as KnowledgeMetadata, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, X as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, B as RoutingDecision, M as RoutingLog, Y as SchemaAgent, Z as SchemaQuestion, p as SessionContext, N as SessionMetadata, q as SessionState, e as SessionStatus, y as StorageContext, z as StorageSetOptions } from './types-DYJ44S2E.js';
 
 /**
  * UCP (Universal Classification Protocol) Types
@@ -680,6 +680,14 @@ interface PlatformKnowledgeSummary {
     type?: string;
     /** Owning organization ID */
     organizationId: string;
+    /**
+     * True for handler-managed documents created through the protocol
+     * write API. System-owned knowledge is hidden from every Studio UI
+     * surface and only appears in `list` when `includeSystemOwned` is set.
+     */
+    isSystemOwned?: boolean;
+    /** Whether semantic search (record embedding) is enabled. */
+    ragEnabled?: boolean;
     /** Timestamps */
     createdAt?: number | string;
     updatedAt?: number | string;
@@ -698,7 +706,74 @@ interface ListKnowledgeOptions {
      * `publicReadable` in Studio).
      */
     orgId?: string;
+    /**
+     * Include system-owned (handler-managed) knowledge in the listing.
+     * Only honored when listing the token's own org; other orgs never
+     * expose their system-owned documents.
+     */
+    includeSystemOwned?: boolean;
 }
+/** Sheet definition for `knowledge.create`. */
+interface CreateKnowledgeSheet {
+    /** Stable sheet id, referenced later by record writes and search. */
+    id: string;
+    name: string;
+    description?: string;
+    /**
+     * Column definitions ({ id, name, type, ... }). Loose-typed; the
+     * Studio schema validates `type` against its column-type enum.
+     */
+    columns?: Array<Record<string, unknown>>;
+}
+interface CreateKnowledgeOptions {
+    description?: string;
+    /**
+     * Enable semantic search at creation time. Defaults to false; can be
+     * flipped later with `setRagEnabled` (which also backfills embeddings
+     * for records inserted while the flag was off).
+     */
+    ragEnabled?: boolean;
+}
+/** A raw record as returned by the protocol record-write endpoints. */
+interface PlatformKnowledgeRecord {
+    id: string;
+    knowledgeId: string;
+    sheetId: string;
+    data: Record<string, unknown>;
+    createdAt?: number | string;
+    updatedAt?: number | string;
+}
+interface KnowledgeSearchOptions {
+    /** Max records to return (server-side clamped to 1..50, default 10). */
+    limit?: number;
+    /**
+     * Optional sheet filter. Pass a sheet id (from the knowledge document)
+     * to restrict the search to that sheet. Omit to search across all
+     * sheets in the knowledge.
+     */
+    sheetId?: string;
+}
+/**
+ * A single hit from `client.knowledge.search`. `score` is the Atlas
+ * vector similarity score (cosine in our setup, so higher is closer).
+ * `data` mirrors the underlying record fields (column id -> value).
+ */
+interface PlatformKnowledgeSearchHit {
+    id: string;
+    knowledgeId: string;
+    sheetId: string;
+    data: Record<string, unknown>;
+    score: number;
+    createdAt?: number | string;
+    updatedAt?: number | string;
+}
+/**
+ * Helplines query params — passed verbatim to Throughline. Loose-typed
+ * so the SDK stays compatible with new Throughline query keys without
+ * a release. Required by Throughline today: `country_code`. Common
+ * optional keys: `topic`, `contact_method`, `limit`.
+ */
+type ThroughlineHelplinesQuery = Record<string, string | number | boolean | undefined>;
 declare class PlatformError extends Error {
     status: number;
     constructor(message: string, status: number);
@@ -738,8 +813,12 @@ declare class PlatformClient {
      *
      * Reads are allowed when the SDK token's org matches the target org,
      * OR when the target org has `publicReadable: true` on the Studio side.
-     * Writes are not yet exposed here — those still go through the user-
-     * authenticated /api/knowledge routes from the Studio UI.
+     *
+     * Writes target system-owned (handler-managed) knowledge only: the
+     * protocol API stamps everything created here `isSystemOwned: true`,
+     * which keeps it out of every Studio UI surface — Studio acts as a
+     * plain storage + RAG layer for it. UI-managed knowledge cannot be
+     * modified through this surface.
      */
     knowledge: {
         /**
@@ -753,6 +832,108 @@ declare class PlatformClient {
          * publicReadable).
          */
         get: (id: string) => Promise<PlatformKnowledge>;
+        /**
+         * Semantic search over a knowledge's records. Studio embeds the
+         * query server-side (Gemini gemini-embedding-001) and runs Atlas
+         * Vector Search against the `vector_index` on `knowledge_records`.
+         *
+         * Same read access rules as `get` — same-org or publicReadable.
+         *
+         * Returns an empty array (not an error) when the Atlas index is
+         * absent or when nothing matches, so handler code can treat
+         * "no hits" and "RAG not configured yet" identically.
+         */
+        search: (id: string, query: string, options?: KnowledgeSearchOptions) => Promise<PlatformKnowledgeSearchHit[]>;
+        /**
+         * Turn semantic search on or off for a knowledge.
+         *
+         * Writes are strictly same-org — `publicReadable` does NOT confer
+         * write access. Flipping `false -> true` schedules a background
+         * backfill of existing records on the Studio side; this call
+         * returns as soon as the flag is persisted, not when the backfill
+         * finishes.
+         *
+         * Idempotent: setting the flag to its current value is a no-op
+         * (`backfillTriggered` will be `false`).
+         */
+        setRagEnabled: (id: string, enabled: boolean) => Promise<{
+            id: string;
+            ragEnabled: boolean;
+            backfillTriggered: boolean;
+        }>;
+        /**
+         * Create a system-owned database knowledge under the token's org.
+         *
+         * 409 (surfaced as an error) means a knowledge of the same name
+         * already exists in the org. Idempotent callers should recover by
+         * listing with `includeSystemOwned: true` and matching on name.
+         */
+        create: (name: string, sheets: CreateKnowledgeSheet[], options?: CreateKnowledgeOptions) => Promise<PlatformKnowledge>;
+        /**
+         * Delete a system-owned knowledge and all of its records.
+         * Refused (403) for UI-managed knowledge.
+         */
+        delete: (id: string) => Promise<{
+            deletedRecords: number;
+        }>;
+        /**
+         * Append one record to a sheet. Embeds async when ragEnabled.
+         */
+        addRecord: (id: string, sheetId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
+        /**
+         * Replace a record's data payload. Re-embeds async when ragEnabled.
+         */
+        updateRecord: (id: string, recordId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
+        /** Delete one record. */
+        deleteRecord: (id: string, recordId: string) => Promise<void>;
+        /**
+         * Bulk-insert records into one sheet (each array entry becomes one
+         * record's `data`). With `replace: true` the sheet's existing
+         * records are deleted first — the full-resync primitive backfills
+         * use. Server caps a single call at 5000 records.
+         */
+        bulkRecords: (id: string, sheetId: string, records: Array<Record<string, unknown>>, options?: {
+            replace?: boolean;
+        }) => Promise<{
+            insertedCount: number;
+            deletedCount: number;
+        }>;
+    };
+    /**
+     * Throughline (find-a-helpline) surface.
+     *
+     * Handlers used to call api.throughlinecare.com directly, which meant
+     * each handler had to hold OAuth client credentials and re-implement
+     * token caching. Studio holds the per-org credentials on
+     * `Organization.throughline.{clientId,clientSecret}` and proxies the
+     * Throughline endpoints; the SDK token identifies the org server-side
+     * so callers never see the secret.
+     *
+     * Responses are returned as parsed JSON. Studio does not reshape the
+     * Throughline body — these surfaces stay compatible with future
+     * Throughline API additions without a Studio or SDK release.
+     *
+     * Caching (24h on countries + topics, none on helplines) is server-
+     * side; the SDK is stateless.
+     */
+    throughline: {
+        /**
+         * GET /v1/countries — Throughline's country catalog (codes,
+         * names, emergency numbers). Cached 24h server-side.
+         */
+        getCountries: () => Promise<unknown>;
+        /**
+         * GET /v1/topics — Throughline's topic taxonomy used to filter
+         * helpline searches. Cached 24h server-side.
+         */
+        getTopics: () => Promise<unknown>;
+        /**
+         * GET /v1/helplines?country_code=...&topic=...&... — live search,
+         * not cached. The query object is forwarded verbatim to Throughline,
+         * so any new key Throughline adds will work without an SDK change.
+         * Required by Throughline today: `country_code`.
+         */
+        getHelplines: (query: ThroughlineHelplinesQuery) => Promise<unknown>;
     };
 }
 /**
@@ -1027,4 +1208,4 @@ declare class LLMClient {
  */
 declare function createLLMClient(config: LLMClientConfig): LLMClient;
 
-export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };
+export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };