@firststep-studio/sdk 0.7.1 → 0.9.0

package/dist/index.d.mts

@@ -669,6 +669,36 @@ interface PlatformChatbot {
     /** Handler type */
     handlerType?: 'builtin' | 'external';
 }
+interface PlatformKnowledgeSummary {
+    /** Studio knowledge MongoDB ID */
+    id: string;
+    /** Knowledge name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Knowledge type (e.g. 'text', 'database') */
+    type?: string;
+    /** Owning organization ID */
+    organizationId: string;
+    /** Timestamps */
+    createdAt?: number | string;
+    updatedAt?: number | string;
+}
+/**
+ * Full knowledge document (shape mirrors the underlying mongoose doc).
+ * Kept loose because the schema is large and varies by knowledge `type`;
+ * narrow types can be added incrementally as callers need them.
+ */
+type PlatformKnowledge = PlatformKnowledgeSummary & Record<string, unknown>;
+interface ListKnowledgeOptions {
+    /**
+     * Target organization to list knowledge from. If omitted, defaults to
+     * the org associated with the SDK token. Use this to read from a
+     * different org (e.g. a platform-operated shared library marked
+     * `publicReadable` in Studio).
+     */
+    orgId?: string;
+}
 declare class PlatformError extends Error {
     status: number;
     constructor(message: string, status: number);
@@ -703,6 +733,27 @@ declare class PlatformClient {
         ok: boolean;
         modified: number;
     }>;
+    /**
+     * Knowledge / resource surface.
+     *
+     * 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.
+     */
+    knowledge: {
+        /**
+         * List knowledge items for an organization.
+         * Defaults to the SDK token's own org if `orgId` is omitted.
+         */
+        list: (options?: ListKnowledgeOptions) => Promise<PlatformKnowledgeSummary[]>;
+        /**
+         * Fetch a single knowledge item by its Studio ID. The caller must
+         * have read access to the knowledge's owning org (same-org or
+         * publicReadable).
+         */
+        get: (id: string) => Promise<PlatformKnowledge>;
+    };
 }
 /**
  * Create a PlatformClient for calling back to FirstStep Studio.
@@ -773,4 +824,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, 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 };

package/dist/index.d.ts

@@ -669,6 +669,36 @@ interface PlatformChatbot {
     /** Handler type */
     handlerType?: 'builtin' | 'external';
 }
+interface PlatformKnowledgeSummary {
+    /** Studio knowledge MongoDB ID */
+    id: string;
+    /** Knowledge name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Knowledge type (e.g. 'text', 'database') */
+    type?: string;
+    /** Owning organization ID */
+    organizationId: string;
+    /** Timestamps */
+    createdAt?: number | string;
+    updatedAt?: number | string;
+}
+/**
+ * Full knowledge document (shape mirrors the underlying mongoose doc).
+ * Kept loose because the schema is large and varies by knowledge `type`;
+ * narrow types can be added incrementally as callers need them.
+ */
+type PlatformKnowledge = PlatformKnowledgeSummary & Record<string, unknown>;
+interface ListKnowledgeOptions {
+    /**
+     * Target organization to list knowledge from. If omitted, defaults to
+     * the org associated with the SDK token. Use this to read from a
+     * different org (e.g. a platform-operated shared library marked
+     * `publicReadable` in Studio).
+     */
+    orgId?: string;
+}
 declare class PlatformError extends Error {
     status: number;
     constructor(message: string, status: number);
@@ -703,6 +733,27 @@ declare class PlatformClient {
         ok: boolean;
         modified: number;
     }>;
+    /**
+     * Knowledge / resource surface.
+     *
+     * 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.
+     */
+    knowledge: {
+        /**
+         * List knowledge items for an organization.
+         * Defaults to the SDK token's own org if `orgId` is omitted.
+         */
+        list: (options?: ListKnowledgeOptions) => Promise<PlatformKnowledgeSummary[]>;
+        /**
+         * Fetch a single knowledge item by its Studio ID. The caller must
+         * have read access to the knowledge's owning org (same-org or
+         * publicReadable).
+         */
+        get: (id: string) => Promise<PlatformKnowledge>;
+    };
 }
 /**
  * Create a PlatformClient for calling back to FirstStep Studio.
@@ -773,4 +824,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, 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 };