@firststep-studio/sdk 0.7.0 → 0.8.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-DCrYoOfK.mjs';
-export { M as AnalyticsContext, z as ChatbotInfo, B as ClassifierConfig, D as DeploymentInfo, F as FormData, T as FormFieldDefinition, U as FormFieldType, E as FormFieldValue, Q as FormSchema, n as HandlerInfo, Y as HandoffContext, f as HandoffInboundContext, Z as HandoffOptions, v as Helpline, u as HelplineResult, t as HelplineSearchOptions, I as IntegrationContext, s as IntegrationResult, N as InteractionEvent, O as InteractionEventType, K as KnowledgeContext, 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, V as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, y as RoutingDecision, G as RoutingLog, W as SchemaAgent, X as SchemaQuestion, p as SessionContext, J as SessionMetadata, q as SessionState, e as SessionStatus, w as StorageContext, x as StorageSetOptions } from './types-DCrYoOfK.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-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';
 
 /**
  * UCP (Universal Classification Protocol) Types
@@ -66,6 +66,12 @@ interface UCPErrorResponse {
 }
 /**
  * UCP Classifier Info Response
+ *
+ * Returned by `GET /classifiers/:id/info`. Carries enough metadata for a
+ * caller to evaluate routing conditions (level severity comparisons,
+ * category lookups) without having to read the classifier definition out
+ * of the underlying datastore. Platform-internal handlers should treat
+ * this endpoint as the canonical source of classifier shape.
  */
 interface UCPInfoResponse {
     /** Classifier name */
@@ -92,6 +98,49 @@ interface UCPInfoResponse {
         pricePerRequest?: number;
         currency?: string;
     };
+    /**
+     * Classifier id. Useful when the caller has only a URL and wants to
+     * round-trip the id through the response (some UCP servers serve
+     * multiple classifiers behind one base URL).
+     */
+    id?: string;
+    /**
+     * Classifier kind. Lets callers branch on type-specific quirks (e.g.
+     * rubric-based classifiers expose `factors`; case-based don't).
+     */
+    type?: 'case-based' | 'rubric-based' | 'reference' | 'lightweight' | 'custom';
+    /**
+     * Ordered list of severity levels emitted by the classifier. Order is
+     * the canonical priority order (`position` ascending). Routing-condition
+     * evaluators compare a classification result's `level` against this list
+     * to honor `>=` / `<=` operators on level labels.
+     */
+    levels?: Array<{
+        id: string;
+        position: number;
+        label: string;
+        threshold?: number;
+        description?: string;
+        color?: string;
+    }>;
+    /**
+     * Categories the classifier emits. Mostly used for UI / display, but
+     * surfaced here so handlers can present category labels without a
+     * second metadata lookup.
+     */
+    categories?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+        position?: number;
+        emoji?: string;
+    }>;
+    /**
+     * Default conversation-turn window the classifier uses. Useful when a
+     * caller needs to truncate history before classifying (mirrors the
+     * Studio classifier model's `conversationTurns` field).
+     */
+    conversationTurns?: number;
 }
 /**
  * UCP Client configuration
@@ -557,6 +606,57 @@ interface PlatformClientConfig {
     /** Request timeout in ms (default: 10000) */
     timeout?: number;
 }
+interface PlatformOrganization {
+    /** Studio organization ID */
+    id: string;
+    /** Display name (null if the organization record has been deleted) */
+    name: string | null;
+    /** URL-safe slug */
+    slug: string | null;
+}
+interface PlatformTokenInfo {
+    /** API token ID */
+    id: string;
+    /** Human-friendly token label */
+    name: string;
+    /** Authorized scopes */
+    scopes: string[];
+    /** Project IDs this token is scoped to (null = full org access) */
+    projectIds: string[] | null;
+}
+interface PlatformIdentity {
+    organization: PlatformOrganization;
+    token: PlatformTokenInfo;
+}
+interface PlatformChatbotRegisterInput {
+    /** Stable handler-side identifier used to upsert (e.g. handler config ID). */
+    externalId: string;
+    /** Display name shown in Studio's chatbot list. */
+    name: string;
+    /** Optional human description. */
+    description?: string;
+    /** Public URL where Studio should send protocol requests. */
+    handlerUrl: string;
+    /** Slug for multi-config routing on the handler side. */
+    configSlug?: string;
+    /** Optional capability flags advertised to Studio. */
+    capabilities?: {
+        streaming?: boolean;
+        formQuestions?: boolean;
+        knowledgeActions?: boolean;
+        integrations?: boolean;
+        [key: string]: unknown;
+    };
+}
+interface PlatformChatbotRegistration {
+    /** Studio chatbot MongoDB ID (immutable across re-registrations). */
+    id: string;
+    /** Echoes back the externalId used as upsert key. */
+    externalId: string;
+    /** Resolved name as stored in Studio. */
+    name: string;
+    protocolConfig: Record<string, unknown>;
+}
 interface PlatformChatbot {
     /** Studio chatbot MongoDB ID */
     id: string;
@@ -578,11 +678,31 @@ declare class PlatformClient {
     private token;
     private timeout;
     constructor(config: PlatformClientConfig);
+    private request;
+    /**
+     * Resolve the organization and token metadata for the configured token.
+     * Useful for connection state UI ("Connected to {orgName}") and audit.
+     */
+    getMe(): Promise<PlatformIdentity>;
     /**
      * List chatbots accessible to this handler's organization.
      * Studio resolves the organization from the API token.
      */
     listChatbots(): Promise<PlatformChatbot[]>;
+    /**
+     * Register or update an external-handler chatbot under the token's
+     * organization. Idempotent: identified by `externalId`, so handlers
+     * can call this on every config save without creating duplicates.
+     */
+    registerChatbot(input: PlatformChatbotRegisterInput): Promise<PlatformChatbotRegistration>;
+    /**
+     * Mark the chatbot identified by `externalId` as disconnected.
+     * The Studio record is preserved (history, analytics survive).
+     */
+    unregisterChatbot(externalId: string): Promise<{
+        ok: boolean;
+        modified: number;
+    }>;
 }
 /**
  * Create a PlatformClient for calling back to FirstStep Studio.
@@ -653,4 +773,207 @@ declare function createAuthHeader(token: string): string;
  */
 declare function isValidToken(token: string): boolean;
 
-export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, 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, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };
+/**
+ * LLM Client
+ *
+ * SDK client for calling Studio's `/api/llm/*` proxy routes. Studio forwards
+ * the request body 1:1 to Google's Generative Language REST API, so the
+ * shapes here mirror Google's REST shape (NOT the @google/genai SDK shape).
+ *
+ * Reference: https://ai.google.dev/api/generate-content
+ *
+ * @example
+ * ```typescript
+ * import { createLLMClient } from '@firststep-studio/sdk';
+ *
+ * const llm = createLLMClient({
+ *   studioUrl: 'https://studio-api.example.com',
+ *   token: process.env.FIRSTSTEP_TOKEN!,
+ * });
+ *
+ * // Single-shot
+ * const res = await llm.generate({
+ *   model: 'gemini-3-flash-preview',
+ *   contents: [{ role: 'user', parts: [{ text: 'Hello' }] }],
+ *   generationConfig: { temperature: 0.7, maxOutputTokens: 500 },
+ * });
+ * console.log(res.candidates[0].content.parts[0].text);
+ *
+ * // Streaming
+ * for await (const chunk of llm.generateStream({
+ *   model: 'gemini-3-flash-preview',
+ *   contents: [{ role: 'user', parts: [{ text: 'Count to 5' }] }],
+ * })) {
+ *   process.stdout.write(chunk.candidates?.[0]?.content?.parts?.[0]?.text ?? '');
+ * }
+ *
+ * // Cache
+ * const cache = await llm.cache.create({
+ *   model: 'models/gemini-2.5-flash',
+ *   systemInstruction: { parts: [{ text: 'long system prompt...' }] },
+ *   ttl: '3600s',
+ * });
+ * await llm.cache.get(cache.name);
+ * await llm.cache.delete(cache.name);
+ * ```
+ */
+interface LLMClientConfig {
+    /** Studio backend API URL (e.g. https://studio-api.example.com) */
+    studioUrl: string;
+    /** API token (Bearer fst_<...>) */
+    token: string;
+    /** Request timeout in ms for non-streaming calls (default: 60000) */
+    timeout?: number;
+}
+interface LLMPart {
+    text?: string;
+    inlineData?: {
+        mimeType: string;
+        data: string;
+    };
+    [k: string]: unknown;
+}
+interface LLMContent {
+    role?: 'user' | 'model';
+    parts: LLMPart[];
+}
+interface LLMGenerationConfig {
+    temperature?: number;
+    maxOutputTokens?: number;
+    topP?: number;
+    topK?: number;
+    responseMimeType?: string;
+    responseSchema?: Record<string, unknown>;
+    thinkingConfig?: {
+        thinkingBudget?: number;
+        thinkingLevel?: 'minimal' | 'low' | 'medium' | 'high';
+        includeThoughts?: boolean;
+    };
+    stopSequences?: string[];
+    [k: string]: unknown;
+}
+interface LLMSafetySetting {
+    category: string;
+    threshold: string;
+}
+/**
+ * Request body for /api/llm/generate and /api/llm/generate/stream.
+ * Mirrors Google's `:generateContent` REST request, plus `model` at the top level
+ * so Studio can build the URL path.
+ */
+interface LLMGenerateRequest {
+    model: string;
+    contents: LLMContent[];
+    systemInstruction?: {
+        parts: LLMPart[];
+    };
+    generationConfig?: LLMGenerationConfig;
+    safetySettings?: LLMSafetySetting[];
+    /** Resource name of an explicit cache, e.g. "cachedContents/abc123" */
+    cachedContent?: string;
+    /** Function-calling tools (forwarded as-is) */
+    tools?: unknown[];
+    [k: string]: unknown;
+}
+interface LLMUsageMetadata {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    cachedContentTokenCount?: number;
+    thoughtsTokenCount?: number;
+    totalTokenCount?: number;
+    [k: string]: unknown;
+}
+interface LLMCandidate {
+    content?: LLMContent;
+    finishReason?: string;
+    index?: number;
+    safetyRatings?: unknown[];
+    [k: string]: unknown;
+}
+interface LLMGenerateResponse {
+    candidates?: LLMCandidate[];
+    usageMetadata?: LLMUsageMetadata;
+    promptFeedback?: {
+        blockReason?: string;
+        [k: string]: unknown;
+    };
+    modelVersion?: string;
+    responseId?: string;
+    [k: string]: unknown;
+}
+interface LLMCacheCreateRequest {
+    model: string;
+    displayName?: string;
+    systemInstruction?: {
+        parts: LLMPart[];
+    };
+    contents?: LLMContent[];
+    /** Time-to-live, e.g. "3600s" */
+    ttl?: string;
+    [k: string]: unknown;
+}
+interface LLMCachedContent {
+    name: string;
+    model: string;
+    createTime?: string;
+    updateTime?: string;
+    expireTime?: string;
+    displayName?: string;
+    usageMetadata?: {
+        totalTokenCount?: number;
+    };
+    [k: string]: unknown;
+}
+declare class LLMError extends Error {
+    status: number;
+    body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+declare class LLMClient {
+    private studioUrl;
+    private token;
+    private timeout;
+    constructor(config: LLMClientConfig);
+    private headers;
+    /**
+     * Single-shot generation. Body is forwarded to Google's :generateContent
+     * unchanged. Response is Google's response shape unchanged.
+     */
+    generate(req: LLMGenerateRequest): Promise<LLMGenerateResponse>;
+    /**
+     * Streaming generation as an AsyncGenerator of partial responses.
+     * Each yielded chunk has the same shape as a non-streaming response (a
+     * `candidates[]` slice with the next text fragment, plus usageMetadata
+     * on the final chunk).
+     *
+     * Note: timeout option is not enforced for streams; consumer should
+     * abort externally if needed.
+     */
+    generateStream(req: LLMGenerateRequest): AsyncGenerator<LLMGenerateResponse>;
+    /**
+     * Explicit prompt cache surface. Maps to Google's `/cachedContents` REST API.
+     */
+    cache: {
+        /**
+         * Create an explicit cache. Returns the resource (use `cache.name` as the
+         * `cachedContent` field on a future generate() request).
+         */
+        create: (req: LLMCacheCreateRequest) => Promise<LLMCachedContent>;
+        /**
+         * Fetch a cache by resource name (e.g. "cachedContents/abc123").
+         * Returns null when the cache is not found (404), which is the common
+         * "expired" signal — callers can simply recreate.
+         */
+        get: (name: string) => Promise<LLMCachedContent | null>;
+        /**
+         * Delete a cache by resource name. Idempotent: 404 is treated as success.
+         */
+        delete: (name: string) => Promise<void>;
+    };
+}
+/**
+ * Create an LLMClient that talks to Studio's /api/llm/* proxy routes.
+ */
+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, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, 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 };