@deepraxis/sdk 0.1.0-dev.5e0f28e → 0.1.0-dev.6898104

package/dist/generated/types.gen.d.ts

@@ -714,7 +714,7 @@ export type BrowserStreamMessage = {
 };
 export type OwnFileCreateFileRequest = {
     /**
-     * File bytes in one multipart file part, not a filename or file ID. The file must be nonempty and at most 104857600 bytes; its content determines the MIME type.
+     * File bytes in one multipart file part, not a filename or file ID. The file must be nonempty and at most 100000000 bytes; its content determines the MIME type.
      */
     file: Blob | File;
     /**
@@ -739,7 +739,7 @@ export type OwnFileCreateFileRequest = {
  */
 export type OwnFileOpenAiFile = {
     /**
-     * File identifier: file_dp_ followed by a 26-character uppercase Crockford ULID. Use the ID returned by upload or list.
+     * File identifier: file- followed by 24 base62 characters. Use the ID returned by upload or list.
      */
     id: string;
     /**
@@ -753,7 +753,7 @@ export type OwnFileOpenAiFile = {
     /**
      * The Unix timestamp (in seconds) for when the file will expire.
      */
-    expires_at?: number;
+    expires_at?: number | null;
     /**
      * The name of the file.
      */
@@ -772,22 +772,12 @@ export type OwnFileOpenAiFile = {
      * @deprecated
      */
     status: 'uploaded' | 'processed' | 'error';
-    /**
-     * Deprecated; always null or absent.
-     *
-     * @deprecated
-     */
-    status_details?: string | null;
     /**
      * Content-detected MIME type.
      */
     mime_type: string;
     /**
-     * Tenant-owned live files can be downloaded through this face.
-     */
-    downloadable: true;
-    /**
-     * Present for session output files.
+     * Session scope for session outputs; null for other files.
      */
     scope?: {
         /**
@@ -798,7 +788,7 @@ export type OwnFileOpenAiFile = {
          * Id of the session the file belongs to.
          */
         id: string;
-    };
+    } | null;
     /**
      * Path within the session output directory; present for session outputs.
      */
@@ -807,6 +797,18 @@ export type OwnFileOpenAiFile = {
      * Session output revision; present for session outputs.
      */
     revision?: number;
+    /**
+     * processing is not yet usable; active is ready; expired cannot be read.
+     */
+    state: 'processing' | 'active' | 'expired';
+    /**
+     * upload is user-provided, generated is platform-produced, session is a session output.
+     */
+    source: 'upload' | 'generated' | 'session';
+    /**
+     * Content digest, prefixed sha256:. Available after processing completes.
+     */
+    sha256: string;
 };
 export type OwnFileErrorResponse = {
     error: OwnFileError;
@@ -835,7 +837,7 @@ export type OwnFileListFilesResponse = {
 };
 export type OwnFileDeleteFileResponse = {
     /**
-     * File identifier: file_dp_ followed by a 26-character uppercase Crockford ULID. Use the ID returned by upload or list.
+     * File identifier: file- followed by 24 base62 characters. Use the ID returned by upload or list.
      */
     id: string;
     /**
@@ -847,6 +849,132 @@ export type OwnFileDeleteFileResponse = {
      */
     deleted: boolean;
 };
+export type OwnFilePraxisCreateUpload = {
+    /**
+     * Exact complete file length in bytes, from 1 through 8000000000; the sum of completed parts must match.
+     */
+    bytes: number;
+    /**
+     * Filename for the resulting file, at most 255 UTF-8 bytes.
+     */
+    filename: string;
+    /**
+     * Declared MIME type; validated against the assembled content.
+     */
+    mime_type: string;
+    /**
+     * Use user_data for conversation attachments, assistants for assistant files, or vision for PNG, JPEG, GIF and WebP images.
+     */
+    purpose: 'user_data' | 'assistants' | 'vision';
+    /**
+     * Optional expiry policy for the resulting file; omission retains the file until deletion.
+     */
+    expires_after?: {
+        /**
+         * Expiry is measured from file creation; created_at is the only supported anchor.
+         */
+        anchor?: 'created_at';
+        /**
+         * Resulting file lifetime in seconds; omit expires_after to retain it until deletion.
+         */
+        seconds: number;
+    };
+    /**
+     * Optional fixed part size in bytes, 5242880–64000000. Requires part_number on every part; retries of identical bytes at the same number return the same part. Omit to use arbitrary-sized parts.
+     */
+    part_size?: number;
+};
+export type OwnFilePraxisUpload = {
+    /**
+     * Upload identifier returned by create. Use this value for parts, complete and cancel.
+     */
+    id: string;
+    /**
+     * Object type; upload identifies an upload session.
+     */
+    object: 'upload';
+    /**
+     * Declared size of the complete file in bytes.
+     */
+    bytes: number;
+    /**
+     * Creation time as Unix seconds.
+     */
+    created_at: number;
+    /**
+     * Expiry time as Unix seconds; unfinished uploads expire after one hour.
+     */
+    expires_at: number;
+    /**
+     * Filename supplied when creating the upload.
+     */
+    filename: string;
+    /**
+     * File purpose: user_data for conversation attachments, assistants for assistant files, vision for images.
+     */
+    purpose: 'user_data' | 'assistants' | 'vision';
+    /**
+     * Upload state: pending accepts parts; completed has a file; cancelled was cancelled; expired exceeded its one-hour lifetime.
+     */
+    status: 'pending' | 'completed' | 'cancelled' | 'expired';
+    /**
+     * Present after complete. A file with status uploaded is still processing; poll files.retrieve until processed before use.
+     */
+    file?: OwnFileOpenAiFile | null;
+    /**
+     * Declared MIME type, verified during assembly.
+     */
+    mime_type?: string;
+    /**
+     * Assembly failure, or null if no failure is recorded.
+     */
+    error?: {
+        /**
+         * File service error code identifying the assembly failure.
+         */
+        code: string;
+        /**
+         * Explanation of why assembly failed.
+         */
+        message: string;
+    } | null;
+};
+export type OwnFilePraxisUploadPart = {
+    /**
+     * Part identifier returned by this request. Supply it to complete in file byte order.
+     */
+    id: string;
+    /**
+     * Object type; upload.part identifies an uploaded part.
+     */
+    object: 'upload.part';
+    /**
+     * Part creation time as Unix seconds.
+     */
+    created_at: number;
+    /**
+     * Parent upload identifier supplied in the request path.
+     */
+    upload_id: string;
+    /**
+     * Accepted part length in bytes.
+     */
+    bytes?: number;
+    /**
+     * Part content digest prefixed sha256:.
+     */
+    sha256?: string;
+};
+export type OwnFilePraxisCompleteUpload = {
+    /**
+     * All part IDs in concatenation order, without duplicates. Fixed-size uploads require increasing part_number order.
+     */
+    part_ids: Array<string>;
+    /**
+     * Optional whole-file MD5 as 32 hexadecimal characters; verified after assembly.
+     */
+    md5?: string;
+};
 /**
  * Problem document returned by the Meta method catalog on failure.
  */
@@ -34421,7 +34549,7 @@ export type FileDeleteFileData = {
     body?: never;
     path: {
         /**
-         * ID of a tenant-owned live file, as returned by upload or list; starts with file_dp_.
+         * ID of a tenant-owned live file, as returned by upload or list; starts with file-.
          */
         file_id: string;
     };
@@ -34450,7 +34578,7 @@ export type FileRetrieveFileData = {
     body?: never;
     path: {
         /**
-         * ID of a tenant-owned live file, as returned by upload or list; starts with file_dp_.
+         * ID of a tenant-owned live file, as returned by upload or list; starts with file-.
          */
         file_id: string;
     };
@@ -34479,7 +34607,7 @@ export type FileRetrieveFileContentData = {
     body?: never;
     path: {
         /**
-         * ID of a tenant-owned live file, as returned by upload or list; starts with file_dp_.
+         * ID of a tenant-owned live file, as returned by upload or list; starts with file-.
          */
         file_id: string;
     };
@@ -34512,6 +34640,139 @@ export type FileRetrieveFileContentResponses = {
     200: Blob | File;
 };
 export type FileRetrieveFileContentResponse = FileRetrieveFileContentResponses[keyof FileRetrieveFileContentResponses];
+export type FileCreateUploadData = {
+    body: OwnFilePraxisCreateUpload;
+    path?: never;
+    query?: never;
+    url: '/file/v1/uploads';
+};
+export type FileCreateUploadErrors = {
+    /**
+     * Invalid upload input or upload state; correct the request before retrying.
+     */
+    400: unknown;
+    /**
+     * The upload is missing or belongs to another organization.
+     */
+    404: unknown;
+    /**
+     * Completion inputs conflict with an earlier completion request.
+     */
+    409: unknown;
+};
+export type FileCreateUploadResponses = {
+    /**
+     * The upload state and, after completion, the resulting file.
+     */
+    200: OwnFilePraxisUpload;
+};
+export type FileCreateUploadResponse = FileCreateUploadResponses[keyof FileCreateUploadResponses];
+export type FileAddUploadPartData = {
+    body: {
+        /**
+         * Raw bytes of this part, nonempty and at most 64000000 bytes.
+         */
+        data: Blob | File;
+    };
+    path: {
+        /**
+         * Upload identifier from create.
+         */
+        upload_id: string;
+    };
+    query?: {
+        /**
+         * Fixed part position, starting at 1.
+         */
+        part_number?: number;
+    };
+    url: '/file/v1/uploads/{upload_id}/parts';
+};
+export type FileAddUploadPartErrors = {
+    /**
+     * Invalid upload input or upload state; correct the request before retrying.
+     */
+    400: unknown;
+    /**
+     * The upload is missing or belongs to another organization.
+     */
+    404: unknown;
+    /**
+     * Completion inputs conflict with an earlier completion request.
+     */
+    409: unknown;
+};
+export type FileAddUploadPartResponses = {
+    /**
+     * The part was accepted.
+     */
+    200: OwnFilePraxisUploadPart;
+};
+export type FileAddUploadPartResponse = FileAddUploadPartResponses[keyof FileAddUploadPartResponses];
+export type FileCompleteUploadData = {
+    body: OwnFilePraxisCompleteUpload;
+    path: {
+        /**
+         * Upload identifier from create.
+         */
+        upload_id: string;
+    };
+    query?: never;
+    url: '/file/v1/uploads/{upload_id}/complete';
+};
+export type FileCompleteUploadErrors = {
+    /**
+     * Invalid upload input or upload state; correct the request before retrying.
+     */
+    400: unknown;
+    /**
+     * The upload is missing or belongs to another organization.
+     */
+    404: unknown;
+    /**
+     * Completion inputs conflict with an earlier completion request.
+     */
+    409: unknown;
+};
+export type FileCompleteUploadResponses = {
+    /**
+     * The upload state and, after completion, the resulting file.
+     */
+    200: OwnFilePraxisUpload;
+};
+export type FileCompleteUploadResponse = FileCompleteUploadResponses[keyof FileCompleteUploadResponses];
+export type FileCancelUploadData = {
+    body?: never;
+    path: {
+        /**
+         * Upload identifier from create.
+         */
+        upload_id: string;
+    };
+    query?: never;
+    url: '/file/v1/uploads/{upload_id}/cancel';
+};
+export type FileCancelUploadErrors = {
+    /**
+     * Invalid upload input or upload state; correct the request before retrying.
+     */
+    400: unknown;
+    /**
+     * The upload is missing or belongs to another organization.
+     */
+    404: unknown;
+    /**
+     * Completion inputs conflict with an earlier completion request.
+     */
+    409: unknown;
+};
+export type FileCancelUploadResponses = {
+    /**
+     * The upload state and, after completion, the resulting file.
+     */
+    200: OwnFilePraxisUpload;
+};
+export type FileCancelUploadResponse = FileCancelUploadResponses[keyof FileCancelUploadResponses];
 export type HealthCheckData = {
     body?: never;
     path?: never;

package/dist/helpers/file-upload.d.ts

@@ -0,0 +1,24 @@
+import type { Praxis } from '../core/client.js';
+import type { OwnFileOpenAiFile } from '../generated/types.gen.js';
+export interface UploadFileOptions {
+    /** user_data for conversation attachments; assistants for assistant files; vision for PNG/JPEG/GIF/WebP. */
+    purpose: 'user_data' | 'assistants' | 'vision';
+    /** Defaults to File.name, or upload for a Blob. */
+    filename?: string;
+    /** Fixed part size in bytes, 5 MiB–64 MB; defaults to 50 MiB. */
+    partSize?: number;
+    /** Concurrent part requests, a positive integer; defaults to 3. */
+    concurrency?: number;
+    /** Aborts outstanding requests and cancels an unfinished Upload. */
+    signal?: AbortSignal;
+    /** Acknowledged byte fraction, 0–1. A value of 1 does not imply processing has finished. */
+    onProgress?: (fraction: number) => void;
+}
+export type UploadedFile = OwnFileOpenAiFile;
+/** Upload a nonempty file up to 2 GiB, returning only after processing reaches active.
+ * Files up to 32 MiB use one request; larger files use fixed-size Uploads parts.
+ * Parts and complete each retry transient failures at most five times with exponential backoff.
+ * A terminal failure or abort cancels the Upload. Completed files cannot be cancelled;
+ * if abort occurs during processing, delete the resulting file explicitly if no longer needed.
+ */
+export declare function uploadFile(client: Pick<Praxis, 'file'>, file: Blob | File, options: UploadFileOptions): Promise<UploadedFile>;

package/dist/helpers/file-upload.js

@@ -0,0 +1,113 @@
+import { PraxisError, PraxisConnectionError, PraxisTimeoutError } from "../core/errors.js";
+import { sleep } from "../core/retry.js";
+const MAX_RETRIES = 5;
+function retryable(error) {
+    return error instanceof PraxisConnectionError || error instanceof PraxisTimeoutError
+        || error instanceof SyntaxError
+        || (error instanceof PraxisError && (error.status === 408 || error.status === 429 || (error.status !== undefined && error.status >= 500 && error.status <= 599)));
+}
+async function retry(signal, operation) {
+    for (let used = 0;; used++) {
+        signal.throwIfAborted();
+        try {
+            return await operation();
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            if (used >= MAX_RETRIES || !retryable(error))
+                throw error;
+            await sleep(500 * 2 ** used, signal);
+        }
+    }
+}
+/** Upload a nonempty file up to 2 GiB, returning only after processing reaches active.
+ * Files up to 32 MiB use one request; larger files use fixed-size Uploads parts.
+ * Parts and complete each retry transient failures at most five times with exponential backoff.
+ * A terminal failure or abort cancels the Upload. Completed files cannot be cancelled;
+ * if abort occurs during processing, delete the resulting file explicitly if no longer needed.
+ */
+export async function uploadFile(client, file, options) {
+    options.signal?.throwIfAborted();
+    if (file.size < 1 || file.size > 2 * 1024 ** 3)
+        throw new RangeError('File size must be 1 byte through 2 GiB');
+    const partSize = options.partSize ?? 50 * 1024 ** 2;
+    const concurrency = options.concurrency ?? 3;
+    if (!Number.isSafeInteger(partSize) || partSize < 5 * 1024 ** 2 || partSize > 64_000_000)
+        throw new RangeError('partSize must be an integer from 5242880 through 64000000');
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1)
+        throw new RangeError('concurrency must be a positive integer');
+    const filename = options.filename ?? (typeof File !== 'undefined' && file instanceof File ? file.name : 'upload');
+    const work = new AbortController();
+    const abort = () => work.abort(options.signal?.reason);
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const signal = work.signal;
+    const request = { signal, maxRetries: 0, timeoutMs: 120_000 };
+    let uploadId;
+    const active = async (initial) => {
+        let result = initial;
+        for (let polls = 0;; polls++) {
+            signal.throwIfAborted();
+            if (result.state === 'active')
+                return result;
+            if (result.state !== 'processing')
+                throw new PraxisError({ code: 'FILE_PROCESSING_FAILED', message: `File ${result.id} is not active (${result.state})` });
+            await sleep(Math.min(5000, 1000 * 2 ** polls), signal);
+            result = await retry(signal, () => client.file.files.retrieve({ path: { file_id: result.id }, ...request }));
+        }
+    };
+    try {
+        signal.throwIfAborted();
+        options.onProgress?.(0);
+        if (file.size <= 32 * 1024 ** 2) {
+            const result = await client.file.files.create({ body: { file: new File([file], filename, { type: file.type }), purpose: options.purpose }, ...request });
+            options.onProgress?.(1);
+            return await active(result);
+        }
+        const upload = await client.file.uploads.create({ body: { bytes: file.size, filename, mime_type: file.type || 'application/octet-stream', purpose: options.purpose, part_size: partSize }, ...request });
+        uploadId = upload.id;
+        signal.throwIfAborted();
+        const path = { upload_id: uploadId };
+        const count = Math.ceil(file.size / partSize);
+        const ids = new Array(count);
+        let cursor = 0, confirmed = 0;
+        const worker = async () => {
+            while (cursor < count) {
+                signal.throwIfAborted();
+                const index = cursor++;
+                const chunk = file.slice(index * partSize, Math.min(file.size, (index + 1) * partSize));
+                const part = await retry(signal, () => client.file.uploads.parts.create({ path, query: { part_number: index + 1 }, body: { data: new File([chunk], filename) }, ...request }));
+                ids[index] = part.id;
+                confirmed += chunk.size;
+                options.onProgress?.(confirmed / file.size);
+            }
+        };
+        const workers = Array.from({ length: Math.min(concurrency, count) }, worker);
+        try {
+            await Promise.all(workers);
+        }
+        catch (error) {
+            work.abort();
+            await Promise.allSettled(workers);
+            throw error;
+        }
+        const result = await retry(signal, () => client.file.uploads.complete({ path, body: { part_ids: ids }, ...request }));
+        if (result.error)
+            throw new PraxisError({ code: result.error.code, message: result.error.message });
+        if (result.status !== 'completed' || !result.file)
+            throw new PraxisError({ code: 'INVALID_RESPONSE', message: 'Complete did not return a completed Upload with a file' });
+        return await active(result.file);
+    }
+    catch (error) {
+        work.abort();
+        if (uploadId) {
+            // Cleanup uses its own timeout and must not inherit the aborted work signal.
+            await client.file.uploads.cancel({ path: { upload_id: uploadId }, maxRetries: 0, timeoutMs: 10_000 }).catch(() => { });
+        }
+        if (options.signal?.aborted)
+            throw options.signal.reason;
+        throw error;
+    }
+    finally {
+        options.signal?.removeEventListener('abort', abort);
+    }
+}

package/dist/index.d.ts

@@ -9,3 +9,5 @@ export { publish } from './helpers/application-publish.js';
 export type { PublishInput, PublishResult, AssetsConfig } from './helpers/application-publish.js';
 export { count } from './helpers/database-count.js';
 export type { CountInput, CountResult } from './helpers/database-count.js';
+export { uploadFile } from './helpers/file-upload.js';
+export type { UploadFileOptions, UploadedFile } from './helpers/file-upload.js';

package/dist/index.js

@@ -4,3 +4,4 @@ export { Page } from "./core/pagination.js";
 export { parseSSE } from "./core/sse.js";
 export { publish } from "./helpers/application-publish.js";
 export { count } from "./helpers/database-count.js";
+export { uploadFile } from "./helpers/file-upload.js";