openai 7.4.0 → 7.6.0

package/src/lib/transform.ts

@@ -1,4 +1,5 @@
 import type { JSONSchema, JSONSchemaDefinition } from './jsonschema';
+import { hasOwn } from '../internal/utils';
 
 const JSON_SCHEMA_ANNOTATION_KEYWORDS = new Set([
   '$comment',
@@ -86,8 +87,27 @@ const MERGEABLE_OBJECT_ALL_OF_KEYWORDS = new Set([
   'type',
 ]);
 
+/** Visits a nested schema together with its root-relative path and containing schema keyword. */
 type JSONSchemaChildVisitor = (schema: unknown, path: string[], keyword: string) => void;
 
+/** Assigns schema keywords without invoking the inherited `__proto__` setter. */
+function assignSchema<T extends object>(target: T, ...sources: object[]): T {
+  for (const source of sources) {
+    if (Object.prototype.propertyIsEnumerable.call(source, '__proto__') && !hasOwn(target, '__proto__')) {
+      Object.defineProperty(target, '__proto__', {
+        value: undefined,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+    }
+
+    Object.assign(target, source);
+  }
+
+  return target;
+}
+
 /**
  * Visits only values carried by JSON Schema keywords that contain schemas.
  * Literal payloads such as enum, const, and default deliberately do not
@@ -119,17 +139,29 @@ export function forEachJSONSchemaChild(
 
   for (const keyword of JSON_SCHEMA_MAP_SCHEMA_KEYWORDS) {
     const children = record[keyword];
-    if (!isObject(children)) continue;
+    if (!isObject(children)) {
+      continue;
+    }
 
     for (const [key, child] of Object.entries(children)) {
       // Draft 7 dependencies also permits property dependency arrays. They
       // are not schemas and must not be traversed as literal JSON payloads.
-      if (keyword === 'dependencies' && !isSchemaDefinition(child)) continue;
+      if (keyword === 'dependencies' && !isSchemaDefinition(child)) {
+        continue;
+      }
       visit(child, [...path, keyword, key], keyword);
     }
   }
 }
 
+/**
+ * Returns a cloned schema normalized for strict Structured Outputs.
+ *
+ * Object properties become required, object schemas are closed to additional
+ * properties, and representable local references and intersections are preserved.
+ *
+ * @throws {Error} If the schema cannot be represented without changing its validation semantics.
+ */
 export function toStrictJsonSchema(schema: JSONSchema): JSONSchema {
   const schemaCopy = structuredClone(schema);
   // JSON serialization omits undefined object properties. Drop optional
@@ -170,10 +202,7 @@ export function toStrictJsonSchema(schema: JSONSchema): JSONSchema {
   return strictSchema;
 }
 
-function stripUndefinedSchemaKeywords(
-  schema: JSONSchemaDefinition,
-  visited: Set<JSONSchema> = new Set(),
-): void {
+function stripUndefinedSchemaKeywords(schema: JSONSchemaDefinition, visited = new Set<JSONSchema>()): void {
   if (typeof schema === 'boolean' || !isObject(schema) || visited.has(schema)) {
     return;
   }
@@ -307,7 +336,7 @@ function inlineRootRefObject(schema: JSONSchema): void {
   for (const keyword of Object.keys(schema)) {
     delete schemaRecord[keyword];
   }
-  Object.assign(schema, inlined, inheritedAnnotations, rootMetadata);
+  assignSchema(schema, inlined, inheritedAnnotations, rootMetadata);
   if (rootDefinitions !== undefined) {
     schema.$defs = rootDefinitions;
   }
@@ -357,7 +386,7 @@ function normalizeRootAllOf(schema: JSONSchema): void {
     for (const keyword of Object.keys(schema)) {
       delete schemaRecord[keyword];
     }
-    Object.assign(schema, normalized, rootMetadata);
+    assignSchema(schema, normalized, rootMetadata);
   }
 }
 
@@ -404,7 +433,12 @@ function normalizeRootAnyOf(schema: JSONSchema): boolean {
     const renames = definitionRenames.get(keyword);
     const mergedDefinitions: Record<string, JSONSchemaDefinition> = { ...rootDefinitions };
     for (const [name, definition] of Object.entries(branchDefinitions)) {
-      mergedDefinitions[renames?.get(name) ?? name] = definition as JSONSchemaDefinition;
+      Object.defineProperty(mergedDefinitions, renames?.get(name) ?? name, {
+        value: definition,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
     }
     normalized[keyword] = mergedDefinitions;
     delete rootMetadata[keyword];
@@ -415,7 +449,7 @@ function normalizeRootAnyOf(schema: JSONSchema): boolean {
   for (const keyword of Object.keys(schema)) {
     delete schemaRecord[keyword];
   }
-  Object.assign(schema, normalized, rootMetadata);
+  assignSchema(schema, normalized, rootMetadata);
   return true;
 }
 
@@ -445,10 +479,7 @@ function planPromotedRootAnyOfDefinitionRenames(
     let aliasIndex = 0;
 
     for (const [name, definition] of Object.entries(branchDefinitions)) {
-      if (
-        !Object.prototype.hasOwnProperty.call(rootDefinitions, name) ||
-        schemasEqual(rootDefinitions[name], definition)
-      ) {
+      if (!hasOwn(rootDefinitions, name) || schemasEqual(rootDefinitions[name], definition)) {
         continue;
       }
 
@@ -493,8 +524,8 @@ function rewriteLocalRefsIntoPromotedRootAnyOfBranch(
       }
     }
 
-    return promotedParts.length === 0 ?
-        '#'
+    return promotedParts.length === 0
+      ? '#'
       : '#/' + promotedParts.map(encodeJSONPointerTokenForURIFragment).join('/');
   };
 
@@ -557,11 +588,7 @@ function normalizeSingletonTypeArrays(schema: JSONSchemaDefinition): void {
   });
 }
 
-function isNullable(
-  schema: JSONSchemaDefinition,
-  root: JSONSchema,
-  seenRefs: Set<string> = new Set(),
-): boolean {
+function isNullable(schema: JSONSchemaDefinition, root: JSONSchema, seenRefs = new Set<string>()): boolean {
   if (typeof schema === 'boolean') {
     return schema;
   }
@@ -600,25 +627,25 @@ function isNullable(
     return false;
   }
 
-  if (schema.allOf !== undefined) {
-    if (!Array.isArray(schema.allOf) || !schema.allOf.every((variant) => isNullable(variant, root))) {
-      return false;
-    }
+  if (
+    schema.allOf !== undefined &&
+    (!Array.isArray(schema.allOf) || !schema.allOf.every((variant) => isNullable(variant, root)))
+  ) {
+    return false;
   }
 
-  if (schema.anyOf !== undefined) {
-    if (!Array.isArray(schema.anyOf) || !schema.anyOf.some((variant) => isNullable(variant, root))) {
-      return false;
-    }
+  if (
+    schema.anyOf !== undefined &&
+    (!Array.isArray(schema.anyOf) || !schema.anyOf.some((variant) => isNullable(variant, root)))
+  ) {
+    return false;
   }
 
-  if (schema.oneOf !== undefined) {
-    if (
-      !Array.isArray(schema.oneOf) ||
-      schema.oneOf.filter((variant) => isNullable(variant, root)).length !== 1
-    ) {
-      return false;
-    }
+  if (
+    schema.oneOf !== undefined &&
+    (!Array.isArray(schema.oneOf) || schema.oneOf.filter((variant) => isNullable(variant, root)).length !== 1)
+  ) {
+    return false;
   }
 
   // Conditional and negated schemas need a full JSON Schema evaluator to prove
@@ -680,7 +707,7 @@ function ensureStrictJsonSchema(
   // the same strict handling as type: 'object'. Explicitly open object schemas
   // cannot be represented in Structured Outputs strict mode.
   if (hasObjectShape(jsonSchema)) {
-    if (!('additionalProperties' in jsonSchema)) {
+    if (!hasOwn(jsonSchema, 'additionalProperties')) {
       jsonSchema.additionalProperties = false;
     } else if (jsonSchema.additionalProperties !== false) {
       throw new Error(
@@ -702,7 +729,7 @@ function ensureStrictJsonSchema(
   const properties = jsonSchema.properties;
   if (hasObjectShape(jsonSchema)) {
     for (const key of required) {
-      if (!isObject(properties) || !Object.prototype.hasOwnProperty.call(properties, key)) {
+      if (!isObject(properties) || !hasOwn(properties, key)) {
         throw new Error(
           `Object schema at \`${
             path.join('/') || '<root>'
@@ -730,7 +757,7 @@ function ensureStrictJsonSchema(
   const items = jsonSchema.items;
   const additionalItems = jsonSchema.additionalItems;
   if (Array.isArray(items)) {
-    throw new Error(
+    throw new TypeError(
       `Schema at \`${
         path.join('/') || '<root>'
       }\` uses tuple-form \`items\`, which cannot be represented in strict Structured Outputs.`,
@@ -746,27 +773,25 @@ function ensureStrictJsonSchema(
 
   // Handle intersections (allOf)
   const allOf = jsonSchema.allOf;
-  if (Array.isArray(allOf)) {
-    if (allOf.length === 1 && hasOnlyAnnotationSiblings(jsonSchema, 'allOf')) {
-      const branch = allOf[0]!;
-      if (branch === false) {
-        throw new Error(
-          `Schema at \`${
-            path.join('/') || '<root>'
-          }\` uses \`allOf: [false]\`, which cannot be represented in strict Structured Outputs.`,
-        );
-      }
-      if (branch === true) {
-        // true is the neutral schema for an intersection, so removing this
-        // branch preserves validation while retaining the parent annotations.
-        delete jsonSchema.allOf;
-      } else {
-        const resolved = ensureStrictJsonSchema(branch, [...path, 'allOf', '0'], root);
-        const annotations = { ...jsonSchema };
-        delete annotations.allOf;
-        Object.assign(jsonSchema, resolved, annotations);
-        delete jsonSchema.allOf;
-      }
+  if (Array.isArray(allOf) && allOf.length === 1 && hasOnlyAnnotationSiblings(jsonSchema, 'allOf')) {
+    const branch = allOf[0]!;
+    if (branch === false) {
+      throw new Error(
+        `Schema at \`${
+          path.join('/') || '<root>'
+        }\` uses \`allOf: [false]\`, which cannot be represented in strict Structured Outputs.`,
+      );
+    }
+    if (branch === true) {
+      // true is the neutral schema for an intersection, so removing this
+      // branch preserves validation while retaining the parent annotations.
+      delete jsonSchema.allOf;
+    } else {
+      const resolved = ensureStrictJsonSchema(branch, [...path, 'allOf', '0'], root);
+      const annotations = { ...jsonSchema };
+      delete annotations.allOf;
+      assignSchema(jsonSchema, resolved, annotations);
+      delete jsonSchema.allOf;
     }
   }
 
@@ -859,18 +884,24 @@ function resolvePointerPart(resolved: unknown, part: string): unknown | undefine
     }
 
     const index = Number(part);
-    if (!Object.prototype.hasOwnProperty.call(resolved, index)) {
+    if (!hasOwn(resolved, index)) {
       return undefined;
     }
     return resolved[index];
   }
 
-  if (!isObject(resolved) || !Object.prototype.hasOwnProperty.call(resolved, part)) {
+  if (!isObject(resolved) || !hasOwn(resolved, part)) {
     return undefined;
   }
   return resolved[part];
 }
 
+/**
+ * Resolves a local JSON Pointer through schema-bearing keywords only.
+ *
+ * Returns `undefined` for external references, malformed pointers, missing
+ * targets, and pointers into literal values such as `default` or `enum`.
+ */
 export function resolveLocalRef(root: JSONSchema, ref: string): JSONSchemaDefinition | undefined {
   const parts = parseLocalRef(ref);
   if (parts === undefined) {
@@ -883,7 +914,7 @@ export function resolveLocalRef(root: JSONSchema, ref: string): JSONSchemaDefini
   // forEachJSONSchemaChild so every accepted target is normalized before we
   // advertise the result as strict.
   let resolved: unknown = root;
-  for (let index = 0; index < parts.length; ) {
+  for (let index = 0; index < parts.length;) {
     if (!isObject(resolved)) {
       return undefined;
     }
@@ -929,7 +960,7 @@ export function resolveLocalRef(root: JSONSchema, ref: string): JSONSchemaDefini
   return isSchemaDefinition(resolved) ? resolved : undefined;
 }
 
-function isObject<T>(obj: T | Array<any>): obj is Extract<T, Record<string, any>> {
+function isObject<T>(obj: T | any[]): obj is Extract<T, Record<string, any>> {
   return typeof obj === 'object' && obj !== null && !Array.isArray(obj);
 }
 
@@ -940,7 +971,7 @@ function isSchemaDefinition(value: unknown): value is JSONSchemaDefinition {
 function isObjectOnlySchema(
   schema: JSONSchemaDefinition,
   root: JSONSchema,
-  seenRefs: Set<string> = new Set(),
+  seenRefs = new Set<string>(),
 ): boolean {
   if (typeof schema === 'boolean' || !isObject(schema)) {
     return false;
@@ -969,8 +1000,8 @@ function isObjectOnlySchema(
     }
 
     const branch = schema.allOf[0];
-    return branch !== undefined && branch !== true && branch !== false ?
-        isObjectOnlySchema(branch, root, seenRefs)
+    return branch !== undefined && branch !== true && branch !== false
+      ? isObjectOnlySchema(branch, root, seenRefs)
       : false;
   }
 
@@ -983,7 +1014,7 @@ function isObjectOnlySchema(
 function isArrayOnlySchema(
   schema: JSONSchemaDefinition,
   root: JSONSchema,
-  seenRefs: Set<string> = new Set(),
+  seenRefs = new Set<string>(),
 ): boolean {
   if (typeof schema === 'boolean' || !isObject(schema)) {
     return false;
@@ -1012,8 +1043,8 @@ function isArrayOnlySchema(
     }
 
     const branch = schema.allOf[0];
-    return branch !== undefined && branch !== true && branch !== false ?
-        isArrayOnlySchema(branch, root, seenRefs)
+    return branch !== undefined && branch !== true && branch !== false
+      ? isArrayOnlySchema(branch, root, seenRefs)
       : false;
   }
 
@@ -1023,6 +1054,7 @@ function isArrayOnlySchema(
   );
 }
 
+/** Returns whether a schema contains only a reference, reusable definitions, and annotations. */
 export function hasOnlyRefAndAnnotations(schema: JSONSchema): boolean {
   return Object.keys(schema).every(
     // Definition maps do not add sibling validation constraints, and keeping
@@ -1159,6 +1191,11 @@ function normalizeAnyOfFalseBranches(jsonSchema: JSONSchema): void {
   }
 }
 
+/**
+ * Rejects nested schema resource identifiers that would change local reference scope.
+ *
+ * @throws {Error} If a nested subschema defines its own `$id`.
+ */
 export function assertNoNestedSchemaIds(schema: JSONSchema): void {
   const visit = (value: JSONSchemaDefinition, path: string[]): void => {
     if (typeof value === 'boolean' || !isObject(value)) {
@@ -1289,9 +1326,9 @@ function rewriteLocalRefsIntoFilteredAnyOfBranches(root: JSONSchema): void {
 
     for (const [index, part] of originalParts.entries()) {
       const resolvedRecord =
-        typeof resolved === 'object' && resolved !== null && !Array.isArray(resolved) ?
-          (resolved as Record<string, unknown>)
-        : undefined;
+        typeof resolved === 'object' && resolved !== null && !Array.isArray(resolved)
+          ? (resolved as Record<string, unknown>)
+          : undefined;
       if (
         part === 'anyOf' &&
         index < originalParts.length - 1 &&
@@ -1305,7 +1342,7 @@ function rewriteLocalRefsIntoFilteredAnyOfBranches(root: JSONSchema): void {
         }
 
         const branchIndex = Number(branchIndexPart);
-        if (!Object.prototype.hasOwnProperty.call(branches, branchIndex)) {
+        if (!hasOwn(branches, branchIndex)) {
           return ref;
         }
 
@@ -1399,7 +1436,7 @@ function preserveAllOfRefTargets(root: JSONSchema, rootOnly = false): void {
     }
 
     let alias = '__openai_strict_allOf_ref_' + aliasIndex++;
-    while (Object.prototype.hasOwnProperty.call(definitions, alias)) {
+    while (hasOwn(definitions, alias)) {
       alias = '__openai_strict_allOf_ref_' + aliasIndex++;
     }
     definitions[alias] = structuredClone(target);
@@ -1476,7 +1513,7 @@ function preserveDiscardedAllOfPropertyRefTargets(root: JSONSchema, discardedPat
     }
 
     let alias = '__openai_strict_allOf_property_ref_' + aliasIndex++;
-    while (Object.prototype.hasOwnProperty.call(definitions, alias)) {
+    while (hasOwn(definitions, alias)) {
       alias = '__openai_strict_allOf_property_ref_' + aliasIndex++;
     }
     definitions[alias] = structuredClone(target);
@@ -1606,7 +1643,7 @@ function normalizeObjectAllOfBranches(
   schema: JSONSchemaDefinition,
   path: string[],
   root: JSONSchema,
-  normalizing: Set<JSONSchema> = new Set(),
+  normalizing = new Set<JSONSchema>(),
 ): void {
   if (typeof schema === 'boolean' || !isObject(schema)) {
     return;
@@ -1675,7 +1712,7 @@ export function normalizeObjectAllOfForExclusivity(
       for (const keyword of Object.keys(normalized)) {
         delete (normalized as Record<string, unknown>)[keyword];
       }
-      Object.assign(normalized, flattened, siblings);
+      assignSchema(normalized, flattened, siblings);
     }
 
     return normalized;
@@ -1688,7 +1725,7 @@ function mergeObjectAllOf(
   jsonSchema: JSONSchema,
   path: string[],
   root: JSONSchema,
-  normalizing: Set<JSONSchema> = new Set(),
+  normalizing = new Set<JSONSchema>(),
 ): boolean {
   const allOf = jsonSchema.allOf;
   if (!Array.isArray(allOf) || allOf.length === 0) {
@@ -1762,7 +1799,7 @@ function mergeObjectAllOf(
     }
   }
 
-  const branches: Array<{ schema: JSONSchema; sourcePath: string[] | undefined }> = [];
+  const branches: { schema: JSONSchema; sourcePath: string[] | undefined }[] = [];
   if (parentHasObjectShape) {
     branches.push({ schema: jsonSchema, sourcePath: path });
   }
@@ -1806,11 +1843,11 @@ function mergeObjectAllOf(
   const mergedProperties = Object.create(null) as Record<string, JSONSchemaDefinition>;
   const mergedRequired = new Set<string>();
   const closedPropertySets: Set<string>[] = [];
-  const propertyEntries: Array<{
+  const propertyEntries: {
     key: string;
     propertySchema: JSONSchemaDefinition;
     sourcePath: string[] | undefined;
-  }> = [];
+  }[] = [];
   let sawProperties = false;
   let sawRequired = false;
   let hasExplicitObjectType = false;
@@ -1818,7 +1855,9 @@ function mergeObjectAllOf(
 
   const mergeAnnotations = (schema: JSONSchema) => {
     for (const keyword of JSON_SCHEMA_ANNOTATION_KEYWORDS) {
-      if (!(keyword in schema)) continue;
+      if (!(keyword in schema)) {
+        continue;
+      }
       // Annotation keywords do not affect Draft 7 validation. Preserve the
       // first value (the outer schema, then earlier branches) instead of
       // rejecting an otherwise exactly mergeable intersection.
@@ -1830,7 +1869,9 @@ function mergeObjectAllOf(
 
   mergeAnnotations(jsonSchema);
   for (const resolvedEntry of resolvedEntries) {
-    if (resolvedEntry === undefined) continue;
+    if (resolvedEntry === undefined) {
+      continue;
+    }
     for (const entry of resolvedEntry.refChain) {
       mergeAnnotations(entry);
     }
@@ -1838,7 +1879,9 @@ function mergeObjectAllOf(
 
   for (const { schema: branch, sourcePath } of branches) {
     for (const keyword of Object.keys(branch)) {
-      if (keyword === 'allOf' && branch === jsonSchema) continue;
+      if (keyword === 'allOf' && branch === jsonSchema) {
+        continue;
+      }
       if (
         (keyword === '$defs' || keyword === 'definitions') &&
         isObject((branch as Record<string, unknown>)[keyword])
@@ -1883,7 +1926,9 @@ function mergeObjectAllOf(
         fail();
       }
       sawRequired = true;
-      for (const key of branch.required) mergedRequired.add(key);
+      for (const key of branch.required) {
+        mergedRequired.add(key);
+      }
     }
 
     if ('additionalProperties' in branch) {
@@ -1898,18 +1943,20 @@ function mergeObjectAllOf(
   // closed property sets before merging schemas so optional declarations
   // excluded by another closed branch are discarded, while required excluded
   // properties remain unrepresentable and fail closed.
-  const allowedClosedProperties =
-    closedPropertySets.length === 0 ?
-      undefined
-    : closedPropertySets
-        .slice(1)
-        .reduce(
-          (allowed, keys) => new Set([...allowed].filter((key) => keys.has(key))),
-          new Set(closedPropertySets[0]),
-        );
+  let allowedClosedProperties: Set<string> | undefined;
+  if (closedPropertySets.length > 0) {
+    allowedClosedProperties = new Set(closedPropertySets[0]);
+    for (const keys of closedPropertySets.slice(1)) {
+      for (const key of allowedClosedProperties) {
+        if (!keys.has(key)) {
+          allowedClosedProperties.delete(key);
+        }
+      }
+    }
+  }
+  const closedProperties = allowedClosedProperties;
   const excludesRequiredProperty =
-    allowedClosedProperties !== undefined &&
-    [...mergedRequired].some((key) => !allowedClosedProperties.has(key));
+    closedProperties !== undefined && [...mergedRequired].some((key) => !closedProperties.has(key));
   const collapsesToNull = excludesRequiredProperty && !hasExplicitObjectType && hasExplicitNullableObjectType;
   const discardedPropertyPaths = propertyEntries
     .filter(
@@ -1932,7 +1979,7 @@ function mergeObjectAllOf(
       for (const keyword of Object.keys(jsonSchema)) {
         delete (jsonSchema as any)[keyword];
       }
-      Object.assign(jsonSchema, merged);
+      assignSchema(jsonSchema, merged);
       return true;
     }
     fail();
@@ -1942,10 +1989,7 @@ function mergeObjectAllOf(
     if (allowedClosedProperties !== undefined && !allowedClosedProperties.has(key)) {
       continue;
     }
-    if (
-      Object.prototype.hasOwnProperty.call(mergedProperties, key) &&
-      !schemasEqual(mergedProperties[key], propertySchema)
-    ) {
+    if (hasOwn(mergedProperties, key) && !schemasEqual(mergedProperties[key], propertySchema)) {
       fail();
     }
     mergedProperties[key] = propertySchema;
@@ -1954,14 +1998,20 @@ function mergeObjectAllOf(
   if (hasExplicitObjectType || hasExplicitNullableObjectType) {
     merged.type = hasExplicitObjectType ? 'object' : ['object', 'null'];
   }
-  if (sawProperties) merged.properties = Object.fromEntries(Object.entries(mergedProperties));
-  if (sawRequired) merged.required = [...mergedRequired];
-  if (closedPropertySets.length > 0) merged.additionalProperties = false;
+  if (sawProperties) {
+    merged.properties = Object.fromEntries(Object.entries(mergedProperties));
+  }
+  if (sawRequired) {
+    merged.required = [...mergedRequired];
+  }
+  if (closedPropertySets.length > 0) {
+    merged.additionalProperties = false;
+  }
 
   for (const keyword of Object.keys(jsonSchema)) {
     delete (jsonSchema as any)[keyword];
   }
-  Object.assign(jsonSchema, merged);
+  assignSchema(jsonSchema, merged);
   return true;
 }
 
@@ -2007,8 +2057,10 @@ function schemasEqual(left: unknown, right: unknown): boolean {
 
   const leftRecord = left as Record<string, unknown>;
   const rightRecord = right as Record<string, unknown>;
-  const leftKeys = Object.keys(leftRecord).sort();
-  const rightKeys = Object.keys(rightRecord).sort();
+  const leftKeys = Object.keys(leftRecord);
+  const rightKeys = Object.keys(rightRecord);
+  leftKeys.sort();
+  rightKeys.sort();
 
   if (leftKeys.length !== rightKeys.length) {
     return false;

package/src/lib/vector-store-polling.ts

@@ -0,0 +1,46 @@
+import type { RequestOptions } from '../internal/request-options';
+import type { FileBatches, VectorStoreFileBatch } from '../resources/vector-stores/file-batches';
+import type { Files, VectorStoreFile } from '../resources/vector-stores/files';
+import { pollWithResponse } from './polling';
+
+type PollOptions = RequestOptions & { pollIntervalMs?: number };
+
+/**
+ * Polls an attached file through the resource's retrieve method. Failed files are
+ * returned to the caller, and cancelled files retain their existing retry behavior.
+ *
+ * @internal
+ */
+export function pollVectorStoreFile(
+  resource: Pick<Files, 'retrieve'>,
+  vectorStoreID: string,
+  fileID: string,
+  options?: PollOptions,
+): Promise<VectorStoreFile> {
+  return pollWithResponse(
+    (headers) => resource.retrieve(fileID, { vector_store_id: vectorStoreID }, { ...options, headers }),
+    ['in_progress'],
+    ['failed', 'completed'],
+    options,
+  );
+}
+
+/**
+ * Polls a file batch through the resource's retrieve method until it completes,
+ * fails, or is cancelled. Retrieval errors are propagated unchanged.
+ *
+ * @internal
+ */
+export function pollVectorStoreFileBatch(
+  resource: Pick<FileBatches, 'retrieve'>,
+  vectorStoreID: string,
+  batchID: string,
+  options?: PollOptions,
+): Promise<VectorStoreFileBatch> {
+  return pollWithResponse(
+    (headers) => resource.retrieve(batchID, { vector_store_id: vectorStoreID }, { ...options, headers }),
+    ['in_progress'],
+    ['failed', 'cancelled', 'completed'],
+    options,
+  );
+}