@studyfetch/sdk 1.1.1 → 1.3.0

package/src/resources/v1/components.ts

@@ -7,37 +7,74 @@ import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 export class Components extends APIResource {
-  create(body: ComponentCreateParams, options?: RequestOptions): APIPromise<void> {
-    return this._client.post('/api/v1/components', {
-      body,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  /**
+   * Create a new component
+   *
+   * @example
+   * ```ts
+   * const component = await client.v1.components.create({
+   *   config: {},
+   *   name: 'My Study Component',
+   *   origin: 'chat',
+   *   type: 'chat',
+   * });
+   * ```
+   */
+  create(body: ComponentCreateParams, options?: RequestOptions): APIPromise<ComponentCreateResponse> {
+    return this._client.post('/api/v1/components', { body, ...options });
   }
 
-  retrieve(id: string, options?: RequestOptions): APIPromise<void> {
-    return this._client.get(path`/api/v1/components/${id}`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  /**
+   * Get component by ID
+   *
+   * @example
+   * ```ts
+   * const component = await client.v1.components.retrieve('id');
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<ComponentRetrieveResponse> {
+    return this._client.get(path`/api/v1/components/${id}`, options);
   }
 
-  update(id: string, body: ComponentUpdateParams, options?: RequestOptions): APIPromise<void> {
-    return this._client.patch(path`/api/v1/components/${id}`, {
-      body,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  /**
+   * Update component
+   *
+   * @example
+   * ```ts
+   * const component = await client.v1.components.update('id');
+   * ```
+   */
+  update(
+    id: string,
+    body: ComponentUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<ComponentUpdateResponse> {
+    return this._client.patch(path`/api/v1/components/${id}`, { body, ...options });
   }
 
-  list(query: ComponentListParams, options?: RequestOptions): APIPromise<void> {
-    return this._client.get('/api/v1/components', {
-      query,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  /**
+   * Get all components
+   *
+   * @example
+   * ```ts
+   * const components = await client.v1.components.list();
+   * ```
+   */
+  list(
+    query: ComponentListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ComponentListResponse> {
+    return this._client.get('/api/v1/components', { query, ...options });
   }
 
+  /**
+   * Delete component
+   *
+   * @example
+   * ```ts
+   * await client.v1.components.delete('id');
+   * ```
+   */
   delete(id: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/api/v1/components/${id}`, {
       ...options,
@@ -45,6 +82,12 @@ export class Components extends APIResource {
     });
   }
 
+  /**
+   * @example
+   * ```ts
+   * await client.v1.components.activate('id');
+   * ```
+   */
   activate(id: string, options?: RequestOptions): APIPromise<void> {
     return this._client.post(path`/api/v1/components/${id}/activate`, {
       ...options,
@@ -52,6 +95,12 @@ export class Components extends APIResource {
     });
   }
 
+  /**
+   * @example
+   * ```ts
+   * await client.v1.components.deactivate('id');
+   * ```
+   */
   deactivate(id: string, options?: RequestOptions): APIPromise<void> {
     return this._client.post(path`/api/v1/components/${id}/deactivate`, {
       ...options,
@@ -59,14 +108,28 @@ export class Components extends APIResource {
     });
   }
 
-  embed(id: string, body: ComponentEmbedParams, options?: RequestOptions): APIPromise<void> {
-    return this._client.post(path`/api/v1/components/${id}/embed`, {
-      body,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  /**
+   * Generate embed code for component
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.components.embed('id');
+   * ```
+   */
+  embed(
+    id: string,
+    body: ComponentEmbedParams,
+    options?: RequestOptions,
+  ): APIPromise<ComponentEmbedResponse> {
+    return this._client.post(path`/api/v1/components/${id}/embed`, { body, ...options });
   }
 
+  /**
+   * @example
+   * ```ts
+   * await client.v1.components.interact('id');
+   * ```
+   */
   interact(id: string, options?: RequestOptions): APIPromise<void> {
     return this._client.post(path`/api/v1/components/${id}/interact`, {
       ...options,
@@ -75,18 +138,510 @@ export class Components extends APIResource {
   }
 }
 
-export interface ComponentCreateParams {}
+export interface ComponentCreateResponse {
+  /**
+   * Component ID (MongoDB ObjectId)
+   */
+  _id: string;
+
+  /**
+   * Unique component identifier
+   */
+  componentId: string;
+
+  /**
+   * Component configuration
+   */
+  config: unknown;
+
+  /**
+   * Creation timestamp
+   */
+  createdAt: string;
+
+  /**
+   * Component name
+   */
+  name: string;
+
+  /**
+   * Organization ID
+   */
+  organization: string;
+
+  /**
+   * Component status
+   */
+  status: 'active' | 'inactive' | 'draft';
+
+  /**
+   * Component type
+   */
+  type: 'chat' | 'flashcards' | 'tests' | 'scenarios' | 'explainers' | 'audio-recap';
+
+  /**
+   * Last update timestamp
+   */
+  updatedAt: string;
+
+  /**
+   * Usage statistics
+   */
+  usage: unknown;
+
+  /**
+   * Component description
+   */
+  description?: string;
+}
+
+export interface ComponentRetrieveResponse {
+  /**
+   * Component ID (MongoDB ObjectId)
+   */
+  _id: string;
+
+  /**
+   * Unique component identifier
+   */
+  componentId: string;
+
+  /**
+   * Component configuration
+   */
+  config: unknown;
+
+  /**
+   * Creation timestamp
+   */
+  createdAt: string;
+
+  /**
+   * Component name
+   */
+  name: string;
+
+  /**
+   * Organization ID
+   */
+  organization: string;
+
+  /**
+   * Component status
+   */
+  status: 'active' | 'inactive' | 'draft';
+
+  /**
+   * Component type
+   */
+  type: 'chat' | 'flashcards' | 'tests' | 'scenarios' | 'explainers' | 'audio-recap';
+
+  /**
+   * Last update timestamp
+   */
+  updatedAt: string;
+
+  /**
+   * Usage statistics
+   */
+  usage: unknown;
+
+  /**
+   * Component description
+   */
+  description?: string;
+}
+
+export interface ComponentUpdateResponse {
+  /**
+   * Component ID (MongoDB ObjectId)
+   */
+  _id: string;
+
+  /**
+   * Unique component identifier
+   */
+  componentId: string;
+
+  /**
+   * Component configuration
+   */
+  config: unknown;
+
+  /**
+   * Creation timestamp
+   */
+  createdAt: string;
+
+  /**
+   * Component name
+   */
+  name: string;
+
+  /**
+   * Organization ID
+   */
+  organization: string;
+
+  /**
+   * Component status
+   */
+  status: 'active' | 'inactive' | 'draft';
+
+  /**
+   * Component type
+   */
+  type: 'chat' | 'flashcards' | 'tests' | 'scenarios' | 'explainers' | 'audio-recap';
+
+  /**
+   * Last update timestamp
+   */
+  updatedAt: string;
+
+  /**
+   * Usage statistics
+   */
+  usage: unknown;
+
+  /**
+   * Component description
+   */
+  description?: string;
+}
+
+export type ComponentListResponse = Array<ComponentListResponse.ComponentListResponseItem>;
+
+export namespace ComponentListResponse {
+  export interface ComponentListResponseItem {
+    /**
+     * Component ID (MongoDB ObjectId)
+     */
+    _id: string;
+
+    /**
+     * Unique component identifier
+     */
+    componentId: string;
+
+    /**
+     * Component configuration
+     */
+    config: unknown;
+
+    /**
+     * Creation timestamp
+     */
+    createdAt: string;
+
+    /**
+     * Component name
+     */
+    name: string;
+
+    /**
+     * Organization ID
+     */
+    organization: string;
+
+    /**
+     * Component status
+     */
+    status: 'active' | 'inactive' | 'draft';
+
+    /**
+     * Component type
+     */
+    type: 'chat' | 'flashcards' | 'tests' | 'scenarios' | 'explainers' | 'audio-recap';
+
+    /**
+     * Last update timestamp
+     */
+    updatedAt: string;
+
+    /**
+     * Usage statistics
+     */
+    usage: unknown;
+
+    /**
+     * Component description
+     */
+    description?: string;
+  }
+}
+
+export interface ComponentEmbedResponse {
+  /**
+   * JWT token for authentication
+   */
+  token: string;
 
-export interface ComponentUpdateParams {}
+  /**
+   * Component ID
+   */
+  componentId: string;
+
+  /**
+   * Component type
+   */
+  componentType: string;
+
+  /**
+   * The embed URL for iframe integration
+   */
+  embedUrl: string;
+
+  /**
+   * Token expiration timestamp
+   */
+  expiresAt: string;
+
+  /**
+   * Embed options
+   */
+  options: ComponentEmbedResponse.Options;
+}
+
+export namespace ComponentEmbedResponse {
+  /**
+   * Embed options
+   */
+  export interface Options {
+    /**
+     * Embed height
+     */
+    height?: string;
+
+    /**
+     * Embed width
+     */
+    width?: string;
+  }
+}
+
+export interface ComponentCreateParams {
+  /**
+   * Component-specific configuration
+   */
+  config: unknown;
+
+  /**
+   * Name of the component
+   */
+  name: string;
+
+  /**
+   * Origin of the component
+   */
+  origin: 'chat' | 'classroom' | 'upload' | 'console' | 'api';
+
+  /**
+   * Type of component to create
+   */
+  type:
+    | 'chat'
+    | 'flashcards'
+    | 'scenarios'
+    | 'practice_test'
+    | 'audio_recap'
+    | 'tutor_me'
+    | 'explainers'
+    | 'uploads';
+
+  /**
+   * Component description
+   */
+  description?: string;
+
+  /**
+   * Additional metadata
+   */
+  metadata?: unknown;
+}
+
+export interface ComponentUpdateParams {
+  /**
+   * Component status
+   */
+  status?: 'draft' | 'active' | 'inactive' | 'processing' | 'error';
+}
 
 export interface ComponentListParams {
-  type: string;
+  /**
+   * Filter by component type
+   */
+  type?:
+    | 'chat'
+    | 'flashcards'
+    | 'scenarios'
+    | 'practice_test'
+    | 'audio_recap'
+    | 'tutor_me'
+    | 'explainers'
+    | 'uploads';
 }
 
-export interface ComponentEmbedParams {}
+export interface ComponentEmbedParams {
+  /**
+   * Token expiry time in hours
+   */
+  expiryHours?: number;
+
+  /**
+   * Feature toggles
+   */
+  features?: ComponentEmbedParams.Features;
+
+  /**
+   * Group ID for collaboration
+   */
+  groupId?: string;
+
+  /**
+   * Embed height (e.g., "400px", "100vh")
+   */
+  height?: string;
+
+  /**
+   * Session ID for continuity
+   */
+  sessionId?: string;
+
+  /**
+   * Theme customization
+   */
+  theme?: ComponentEmbedParams.Theme;
+
+  /**
+   * User ID for tracking
+   */
+  userId?: string;
+
+  /**
+   * Embed width (e.g., "100%", "600px")
+   */
+  width?: string;
+}
+
+export namespace ComponentEmbedParams {
+  /**
+   * Feature toggles
+   */
+  export interface Features {
+    /**
+     * Enable component creation
+     */
+    enableComponentCreation?: boolean;
+
+    /**
+     * Enable follow-up questions
+     */
+    enableFollowUps?: boolean;
+
+    /**
+     * Enable history
+     */
+    enableHistory?: boolean;
+
+    /**
+     * Enable image sources
+     */
+    enableImageSources?: boolean;
+
+    /**
+     * Enable outline
+     */
+    enableOutline?: boolean;
+
+    /**
+     * Enable transcript
+     */
+    enableTranscript?: boolean;
+
+    /**
+     * Enable voice input
+     */
+    enableVoice?: boolean;
+
+    /**
+     * Enable web search
+     */
+    enableWebSearch?: boolean;
+
+    /**
+     * Enable web search sources
+     */
+    enableWebSearchSources?: boolean;
+
+    /**
+     * Placeholder text
+     */
+    placeholderText?: string;
+  }
+
+  /**
+   * Theme customization
+   */
+  export interface Theme {
+    /**
+     * Background color (hex)
+     */
+    backgroundColor?: string;
+
+    /**
+     * Border radius
+     */
+    borderRadius?: string;
+
+    /**
+     * Font family
+     */
+    fontFamily?: string;
+
+    /**
+     * Font size
+     */
+    fontSize?: string;
+
+    /**
+     * Hide branding
+     */
+    hideBranding?: boolean;
+
+    /**
+     * Logo URL
+     */
+    logoUrl?: string;
+
+    /**
+     * Padding
+     */
+    padding?: string;
+
+    /**
+     * Primary color (hex)
+     */
+    primaryColor?: string;
+
+    /**
+     * Secondary color (hex)
+     */
+    secondaryColor?: string;
+
+    /**
+     * Text color (hex)
+     */
+    textColor?: string;
+  }
+}
 
 export declare namespace Components {
   export {
+    type ComponentCreateResponse as ComponentCreateResponse,
+    type ComponentRetrieveResponse as ComponentRetrieveResponse,
+    type ComponentUpdateResponse as ComponentUpdateResponse,
+    type ComponentListResponse as ComponentListResponse,
+    type ComponentEmbedResponse as ComponentEmbedResponse,
     type ComponentCreateParams as ComponentCreateParams,
     type ComponentUpdateParams as ComponentUpdateParams,
     type ComponentListParams as ComponentListParams,

package/src/resources/v1/embed/component.ts

@@ -7,6 +7,16 @@ import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
 export class Component extends APIResource {
+  /**
+   * Get component data for embed
+   *
+   * @example
+   * ```ts
+   * await client.v1.embed.component.retrieve('componentId', {
+   *   token: 'token',
+   * });
+   * ```
+   */
   retrieve(componentID: string, query: ComponentRetrieveParams, options?: RequestOptions): APIPromise<void> {
     return this._client.get(path`/api/v1/embed/component/${componentID}`, {
       query,
@@ -15,10 +25,22 @@ export class Component extends APIResource {
     });
   }
 
+  /**
+   * Process embed interaction
+   *
+   * @example
+   * ```ts
+   * await client.v1.embed.component.interact('componentId', {
+   *   token: 'token',
+   *   body: 'body',
+   * });
+   * ```
+   */
   interact(componentID: string, params: ComponentInteractParams, options?: RequestOptions): APIPromise<void> {
-    const { token } = params;
+    const { token, body } = params;
     return this._client.post(path`/api/v1/embed/component/${componentID}/interact`, {
       query: { token },
+      body: body,
       ...options,
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
@@ -26,11 +48,22 @@ export class Component extends APIResource {
 }
 
 export interface ComponentRetrieveParams {
+  /**
+   * Embed token
+   */
   token: string;
 }
 
 export interface ComponentInteractParams {
+  /**
+   * Query param: Embed token
+   */
   token: string;
+
+  /**
+   * Body param:
+   */
+  body: string;
 }
 
 export declare namespace Component {