@studyfetch/sdk 1.24.0 → 1.26.0

package/src/resources/v1/materials/materials.ts

@@ -2,11 +2,27 @@
 
 import { APIResource } from '../../../core/resource';
 import * as BulkAPI from './bulk';
-import { Bulk } from './bulk';
+import { Bulk, BulkMoveParams, BulkMoveResponse } from './bulk';
 import * as TestAPI from './test';
-import { Test } from './test';
+import {
+  Test,
+  TestPerformOcrResponse,
+  TestProcessEpubResponse,
+  TestProcessImageResponse,
+  TestProcessVideoResponse,
+} from './test';
 import * as UploadAPI from './upload';
-import { Upload, UploadUploadFileParams, UploadUploadFromURLParams } from './upload';
+import {
+  Complete,
+  Upload,
+  UploadCompleteUploadParams,
+  UploadCreatePresignedURLParams,
+  UploadCreatePresignedURLResponse,
+  UploadUploadFileAndProcessParams,
+  UploadUploadFileParams,
+  UploadUploadFromURLParams,
+  UploadUploadURLAndProcessParams,
+} from './upload';
 import { APIPromise } from '../../../core/api-promise';
 import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
@@ -75,107 +91,153 @@ export class Materials extends APIResource {
   }
 
   /**
+   * Create batch upload URLs for multiple materials
+   *
    * @example
    * ```ts
-   * await client.v1.materials.batchCreate();
+   * const response = await client.v1.materials.batchCreate({
+   *   materials: [
+   *     {
+   *       contentType: 'application/pdf',
+   *       filename: 'document.pdf',
+   *       name: 'Chapter 1',
+   *     },
+   *   ],
+   * });
    * ```
    */
-  batchCreate(options?: RequestOptions): APIPromise<void> {
-    return this._client.post('/api/v1/materials/batch', {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  batchCreate(
+    body: MaterialBatchCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<MaterialBatchCreateResponse> {
+    return this._client.post('/api/v1/materials/batch', { body, ...options });
   }
 
   /**
+   * Creates a material and waits for processing to finish before returning. Useful
+   * for synchronous API usage.
+   *
    * @example
    * ```ts
-   * await client.v1.materials.debug('id');
+   * const material = await client.v1.materials.createAndProcess(
+   *   {
+   *     content: { type: 'text' },
+   *     name: 'Chapter 1 - Introduction',
+   *   },
+   * );
    * ```
    */
-  debug(id: string, options?: RequestOptions): APIPromise<void> {
-    return this._client.get(path`/api/v1/materials/${id}/debug`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  createAndProcess(body: MaterialCreateAndProcessParams, options?: RequestOptions): APIPromise<Material> {
+    return this._client.post('/api/v1/materials/upload-and-process', { body, ...options });
   }
 
   /**
+   * Get debug information for a material including extracted content
+   *
    * @example
    * ```ts
-   * await client.v1.materials.getDownloadURL('id', {
-   *   expiresIn: 'expiresIn',
-   * });
+   * const response = await client.v1.materials.debug('id');
+   * ```
+   */
+  debug(id: string, options?: RequestOptions): APIPromise<MaterialDebugResponse> {
+    return this._client.get(path`/api/v1/materials/${id}/debug`, options);
+  }
+
+  /**
+   * Get temporary download URL for material
+   *
+   * @example
+   * ```ts
+   * const response = await client.v1.materials.getDownloadURL(
+   *   'id',
+   * );
    * ```
    */
   getDownloadURL(
     id: string,
-    query: MaterialGetDownloadURLParams,
+    query: MaterialGetDownloadURLParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<void> {
-    return this._client.get(path`/api/v1/materials/${id}/download-url`, {
-      query,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  ): APIPromise<MaterialGetDownloadURLResponse> {
+    return this._client.get(path`/api/v1/materials/${id}/download-url`, { query, ...options });
   }
 
   /**
+   * Move material to a different folder
+   *
    * @example
    * ```ts
-   * await client.v1.materials.move('id');
+   * const material = await client.v1.materials.move('id', {
+   *   folderId: 'folderId',
+   * });
    * ```
    */
-  move(id: string, options?: RequestOptions): APIPromise<void> {
-    return this._client.post(path`/api/v1/materials/${id}/move`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  move(id: string, body: MaterialMoveParams, options?: RequestOptions): APIPromise<Material> {
+    return this._client.post(path`/api/v1/materials/${id}/move`, { body, ...options });
   }
 
   /**
+   * Rename a material
+   *
    * @example
    * ```ts
-   * await client.v1.materials.rename('id');
+   * const material = await client.v1.materials.rename('id', {
+   *   name: 'New Material Name',
+   * });
    * ```
    */
-  rename(id: string, options?: RequestOptions): APIPromise<void> {
-    return this._client.post(path`/api/v1/materials/${id}/rename`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  rename(id: string, body: MaterialRenameParams, options?: RequestOptions): APIPromise<Material> {
+    return this._client.post(path`/api/v1/materials/${id}/rename`, { body, ...options });
   }
 
   /**
+   * Reprocess material to regenerate embeddings and extract content
+   *
    * @example
    * ```ts
-   * await client.v1.materials.reprocess('id');
+   * const material = await client.v1.materials.reprocess('id');
    * ```
    */
-  reprocess(id: string, options?: RequestOptions): APIPromise<void> {
-    return this._client.post(path`/api/v1/materials/${id}/reprocess`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  reprocess(id: string, options?: RequestOptions): APIPromise<Material> {
+    return this._client.post(path`/api/v1/materials/${id}/reprocess`, options);
   }
 
   /**
-   * Search materials using RAG
+   * Search materials using RAG (Retrieval-Augmented Generation)
    *
    * @example
    * ```ts
-   * await client.v1.materials.search({ query: 'query' });
+   * const response = await client.v1.materials.search({
+   *   query: 'What is photosynthesis?',
+   * });
    * ```
    */
-  search(body: MaterialSearchParams, options?: RequestOptions): APIPromise<void> {
-    return this._client.post('/api/v1/materials/search', {
-      body,
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
+  search(body: MaterialSearchParams, options?: RequestOptions): APIPromise<MaterialSearchResponse> {
+    return this._client.post('/api/v1/materials/search', { body, ...options });
   }
 }
 
+export interface Content {
+  /**
+   * Type of content
+   */
+  type: 'text' | 'pdf' | 'video' | 'audio' | 'url';
+
+  /**
+   * URL to fetch content from
+   */
+  sourceUrl?: string;
+
+  /**
+   * Text content (for text type)
+   */
+  text?: string;
+
+  /**
+   * URL to the content (for url type)
+   */
+  url?: string;
+}
+
 export interface Material {
   /**
    * Material ID
@@ -256,11 +318,173 @@ export namespace Material {
 
 export type MaterialListResponse = Array<Material>;
 
+export type MaterialBatchCreateResponse = Array<MaterialBatchCreateResponse.MaterialBatchCreateResponseItem>;
+
+export namespace MaterialBatchCreateResponse {
+  export interface MaterialBatchCreateResponseItem {
+    /**
+     * Material ID
+     */
+    materialId: string;
+
+    /**
+     * Material name
+     */
+    name: string;
+
+    /**
+     * S3 key
+     */
+    s3Key: string;
+
+    /**
+     * Presigned upload URL
+     */
+    uploadUrl: string;
+  }
+}
+
+export interface MaterialDebugResponse {
+  /**
+   * Content details
+   */
+  content: unknown;
+
+  /**
+   * Content type
+   */
+  contentType: string;
+
+  /**
+   * Processed images
+   */
+  images: Array<MaterialDebugResponse.Image>;
+
+  /**
+   * Material ID
+   */
+  materialId: string;
+
+  /**
+   * Material metadata
+   */
+  metadata: unknown;
+
+  /**
+   * Material name
+   */
+  name: string;
+
+  /**
+   * Processing status
+   */
+  status: string;
+
+  /**
+   * Transcript structure for videos
+   */
+  transcriptStructure: unknown | null;
+}
+
+export namespace MaterialDebugResponse {
+  export interface Image {
+    id?: string;
+
+    description?: string;
+
+    pageIndex?: number;
+
+    s3Key?: string;
+
+    s3Url?: string;
+  }
+}
+
+export interface MaterialGetDownloadURLResponse {
+  /**
+   * Temporary download URL
+   */
+  downloadUrl: string;
+}
+
+export interface MaterialSearchResponse {
+  /**
+   * Whether results were filtered by scope
+   */
+  filtered: boolean;
+
+  /**
+   * Original search query
+   */
+  query: string;
+
+  /**
+   * Search results
+   */
+  results: Array<MaterialSearchResponse.Result>;
+
+  /**
+   * Search scope
+   */
+  scope: MaterialSearchResponse.Scope;
+
+  /**
+   * Total number of results
+   */
+  totalResults: number;
+}
+
+export namespace MaterialSearchResponse {
+  export interface Result {
+    /**
+     * Chunk index within the material
+     */
+    chunkIndex: number;
+
+    /**
+     * Material information
+     */
+    material: Result.Material | null;
+
+    /**
+     * Relevance score (0-1)
+     */
+    score: number;
+
+    /**
+     * Matched text chunk
+     */
+    text: string;
+  }
+
+  export namespace Result {
+    /**
+     * Material information
+     */
+    export interface Material {
+      id?: string;
+
+      contentType?: string;
+
+      name?: string;
+    }
+  }
+
+  /**
+   * Search scope
+   */
+  export interface Scope {
+    folderIds?: Array<string>;
+
+    materialIds?: Array<string>;
+  }
+}
+
 export interface MaterialCreateParams {
   /**
    * Content details
    */
-  content: MaterialCreateParams.Content;
+  content: Content;
 
   /**
    * Name of the material
@@ -273,42 +497,90 @@ export interface MaterialCreateParams {
   folderId?: string;
 }
 
-export namespace MaterialCreateParams {
+export interface MaterialListParams {
   /**
-   * Content details
+   * Filter by folder ID
    */
-  export interface Content {
+  folderId?: string;
+}
+
+export interface MaterialBatchCreateParams {
+  /**
+   * Array of materials to create
+   */
+  materials: Array<MaterialBatchCreateParams.Material>;
+}
+
+export namespace MaterialBatchCreateParams {
+  export interface Material {
     /**
-     * Type of content
+     * MIME type
      */
-    type: 'text' | 'pdf' | 'video' | 'audio' | 'url';
+    contentType: string;
 
     /**
-     * URL to fetch content from
+     * Filename
      */
-    sourceUrl?: string;
+    filename: string;
 
     /**
-     * Text content (for text type)
+     * Material name
      */
-    text?: string;
+    name: string;
 
     /**
-     * URL to the content (for url type)
+     * Folder ID
      */
-    url?: string;
+    folderId?: string;
   }
 }
 
-export interface MaterialListParams {
+export interface MaterialCreateAndProcessParams {
   /**
-   * Filter by folder ID
+   * Content details
+   */
+  content: Content;
+
+  /**
+   * Name of the material
+   */
+  name: string;
+
+  /**
+   * Folder ID to place the material in
    */
   folderId?: string;
+
+  /**
+   * Polling interval in milliseconds (default: 2 seconds)
+   */
+  pollIntervalMs?: number;
+
+  /**
+   * Maximum time to wait for processing in milliseconds (default: 5 minutes)
+   */
+  timeoutMs?: number;
 }
 
 export interface MaterialGetDownloadURLParams {
-  expiresIn: string;
+  /**
+   * URL expiration time in seconds (default: 3600)
+   */
+  expiresIn?: number;
+}
+
+export interface MaterialMoveParams {
+  /**
+   * Target folder ID (null for root)
+   */
+  folderId: string | null;
+}
+
+export interface MaterialRenameParams {
+  /**
+   * New name for the material
+   */
+  name: string;
 }
 
 export interface MaterialSearchParams {
@@ -318,18 +590,17 @@ export interface MaterialSearchParams {
   query: string;
 
   /**
-   * Optional: Limit search to materials within specific folders (includes
-   * subfolders)
+   * Limit search to materials within specific folders (includes subfolders)
    */
   folderIds?: Array<string>;
 
   /**
-   * Optional: Limit search to specific material IDs
+   * Limit search to specific material IDs
    */
   materialIds?: Array<string>;
 
   /**
-   * Number of results to return (default: 5)
+   * Number of results to return
    */
   topK?: number;
 }
@@ -340,21 +611,42 @@ Materials.Test = Test;
 
 export declare namespace Materials {
   export {
+    type Content as Content,
     type Material as Material,
     type MaterialListResponse as MaterialListResponse,
+    type MaterialBatchCreateResponse as MaterialBatchCreateResponse,
+    type MaterialDebugResponse as MaterialDebugResponse,
+    type MaterialGetDownloadURLResponse as MaterialGetDownloadURLResponse,
+    type MaterialSearchResponse as MaterialSearchResponse,
     type MaterialCreateParams as MaterialCreateParams,
     type MaterialListParams as MaterialListParams,
+    type MaterialBatchCreateParams as MaterialBatchCreateParams,
+    type MaterialCreateAndProcessParams as MaterialCreateAndProcessParams,
     type MaterialGetDownloadURLParams as MaterialGetDownloadURLParams,
+    type MaterialMoveParams as MaterialMoveParams,
+    type MaterialRenameParams as MaterialRenameParams,
     type MaterialSearchParams as MaterialSearchParams,
   };
 
   export {
     Upload as Upload,
+    type Complete as Complete,
+    type UploadCreatePresignedURLResponse as UploadCreatePresignedURLResponse,
+    type UploadCompleteUploadParams as UploadCompleteUploadParams,
+    type UploadCreatePresignedURLParams as UploadCreatePresignedURLParams,
     type UploadUploadFileParams as UploadUploadFileParams,
+    type UploadUploadFileAndProcessParams as UploadUploadFileAndProcessParams,
     type UploadUploadFromURLParams as UploadUploadFromURLParams,
+    type UploadUploadURLAndProcessParams as UploadUploadURLAndProcessParams,
   };
 
-  export { Bulk as Bulk };
+  export { Bulk as Bulk, type BulkMoveResponse as BulkMoveResponse, type BulkMoveParams as BulkMoveParams };
 
-  export { Test as Test };
+  export {
+    Test as Test,
+    type TestPerformOcrResponse as TestPerformOcrResponse,
+    type TestProcessEpubResponse as TestProcessEpubResponse,
+    type TestProcessImageResponse as TestProcessImageResponse,
+    type TestProcessVideoResponse as TestProcessVideoResponse,
+  };
 }