@gpt-platform/client 0.10.5 → 0.11.0

package/dist/namespaces/storage.d.ts

@@ -0,0 +1,378 @@
+import type { Bucket, StorageFile } from "../_internal/types.gen";
+/** Parameters for requesting a presigned download URL. */
+export interface RequestDownloadUrlParams {
+    /** Time in seconds until the URL expires (default: 3600). */
+    expires_in?: number;
+}
+/** Response from a presigned download URL request. */
+export interface DownloadUrlResponse {
+    /** The presigned download URL. */
+    url: string;
+    /** When the URL expires (ISO 8601). */
+    expires_at: string;
+}
+/** Response from a presigned upload request. */
+export interface PresignedUploadResponse {
+    url?: string;
+    fields?: Record<string, string>;
+    [key: string]: unknown;
+}
+/** Attributes accepted when requesting a presigned upload URL. */
+export type PresignedUploadAttributes = {
+    filename?: string;
+    content_type?: string;
+    [key: string]: unknown;
+};
+/** Attributes accepted when creating a storage bucket. */
+export type CreateBucketAttributes = {
+    workspace_id: string;
+    name: string;
+    [key: string]: unknown;
+};
+/** Attributes accepted when updating a storage bucket (PATCH semantics). */
+export type UpdateBucketAttributes = {
+    name?: string;
+    [key: string]: unknown;
+};
+import type { RequestOptions } from "../base-client";
+import { RequestBuilder } from "../request-builder";
+/**
+ * Creates the storage namespace, providing presigned upload URL generation for
+ * direct browser-to-storage uploads and full bucket management for the
+ * authenticated workspace.
+ *
+ * The platform uses an S3-compatible object storage backend (Google Cloud Storage
+ * in production, MinIO in local development). Files are never routed through the
+ * application server — the client uploads directly to the storage service using
+ * the presigned URL returned by `signUpload()`, which keeps latency low and
+ * avoids egress costs.
+ *
+ * Accessed via `client.storage.*`.
+ *
+ * @param rb - The internal `RequestBuilder` instance used to execute API calls.
+ * @returns An object containing the top-level `signUpload` method and the
+ *   `buckets` sub-namespace.
+ */
+export declare function createStorageNamespace(rb: RequestBuilder): {
+    /**
+     * Generates a presigned S3-compatible URL that allows the browser (or any
+     * HTTP client) to upload a file directly to the platform's object storage
+     * backend without routing the binary data through the application server.
+     *
+     * **Upload flow:**
+     * 1. Call `signUpload()` to obtain a presigned URL and any required form
+     *    fields (for POST-style uploads) or headers (for PUT-style uploads).
+     * 2. Upload the file directly from the browser to the returned URL using
+     *    `fetch` or `XMLHttpRequest`.
+     * 3. After the upload completes, submit the returned storage path to the
+     *    extraction pipeline (e.g., `client.extraction.documents.create(...)`)
+     *    to trigger document processing.
+     *
+     * Presigned URLs are short-lived and must be used promptly after generation.
+     *
+     * @param attributes - Optional record of upload request attributes. Commonly
+     *   used fields include `filename` (the original file name), `content_type`
+     *   (the MIME type of the file, e.g., `"application/pdf"`), and `bucket_id`
+     *   (the target bucket UUID, if not using the workspace default).
+     * @param options - Optional request options such as custom headers or an
+     *   abort signal.
+     * @returns A promise resolving to a record containing at minimum `url` (the
+     *   presigned upload endpoint) and `storage_path` (the object key to
+     *   reference after upload). May also include `fields` for multipart POST
+     *   form uploads.
+     *
+     * @example
+     * ```typescript
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     *
+     * // Step 1: Get a presigned URL
+     * const upload = await client.storage.signUpload({
+     *   filename: 'contract-2026-q1.pdf',
+     *   content_type: 'application/pdf',
+     * });
+     *
+     * // Step 2: Upload the file directly to storage
+     * await fetch(upload.url as string, {
+     *   method: 'PUT',
+     *   body: fileBlob,
+     *   headers: { 'Content-Type': 'application/pdf' },
+     * });
+     *
+     * // Step 3: Hand off to extraction for processing
+     * await client.extraction.documents.create({
+     *   storage_path: upload.storage_path,
+     *   filename: 'contract-2026-q1.pdf',
+     * });
+     * ```
+     */
+    signUpload: (attributes?: PresignedUploadAttributes, options?: RequestOptions) => Promise<PresignedUploadResponse>;
+    /**
+     * Sub-namespace for storage bucket operations.
+     *
+     * Buckets are logical containers that group related files within the workspace.
+     * Each workspace has a default bucket, but ISVs can create additional buckets
+     * to organise files by purpose (e.g., a "contracts" bucket, an "invoices"
+     * bucket). Bucket names must be unique within the workspace. Access control
+     * and retention policies are configured at the bucket level.
+     */
+    buckets: {
+        /**
+         * Returns a single page of storage buckets for the current workspace.
+         *
+         * @param options - Optional pagination and request options.
+         * @param options.page - The 1-based page number to retrieve (default: 1).
+         * @param options.pageSize - The number of buckets to return per page.
+         * @returns A promise resolving to an array of `Bucket` objects for the
+         *   requested page.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const buckets = await client.storage.buckets.list({ pageSize: 20 });
+         * buckets.forEach(b => console.log(b.name, b.file_count));
+         * ```
+         */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<Bucket[]>;
+        /**
+         * Fetches all storage buckets for the current workspace by automatically
+         * paginating through every result page.
+         *
+         * Use this when you need to enumerate all buckets without manual pagination,
+         * for example to render a full bucket selector in a file management UI.
+         *
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to a flat array of all `Bucket` objects
+         *   across every page.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const allBuckets = await client.storage.buckets.listAll();
+         * const defaultBucket = allBuckets.find(b => b.is_default);
+         * console.log(`Default bucket: ${defaultBucket?.name}`);
+         * ```
+         */
+        listAll: (options?: RequestOptions) => Promise<Bucket[]>;
+        /**
+         * Permanently deletes a storage bucket and all of its contents.
+         *
+         * This operation is irreversible. All files stored in the bucket will be
+         * permanently removed from object storage. The default workspace bucket
+         * cannot be deleted. Ensure the bucket is empty or that its contents are
+         * no longer needed before calling this method.
+         *
+         * @param id - The UUID of the bucket to delete.
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to `true` when the deletion succeeds.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * await client.storage.buckets.delete('bkt_01HXYZ...');
+         * console.log('Bucket and all its contents deleted.');
+         * ```
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+        /**
+         * Creates a new storage bucket within the current workspace.
+         *
+         * @param attributes - A record of bucket attributes. Commonly used fields
+         *   include `name` (required, unique within the workspace), `description`
+         *   (optional human-readable label), and `retention_days` (optional number
+         *   of days after which files in this bucket are automatically deleted).
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to the newly created `Bucket` object.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const bucket = await client.storage.buckets.create({
+         *   name: 'contracts',
+         *   description: 'Signed customer contracts',
+         *   retention_days: 2555, // ~7 years
+         * });
+         * console.log(`Bucket created: ${bucket.id}`);
+         * ```
+         */
+        create: (attributes: CreateBucketAttributes, options?: RequestOptions) => Promise<Bucket>;
+        /**
+         * Retrieves a single storage bucket by its unique identifier.
+         *
+         * @param id - The UUID of the bucket to retrieve.
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to the matching `Bucket` object, including
+         *   its name, file count, size, and configuration.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const bucket = await client.storage.buckets.get('bkt_01HXYZ...');
+         * console.log(`Bucket "${bucket.name}" contains ${bucket.file_count} file(s).`);
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<Bucket>;
+        /**
+         * Updates the mutable attributes of an existing storage bucket, such as
+         * its name, description, or retention policy.
+         *
+         * @param id - The UUID of the bucket to update.
+         * @param attributes - A partial record of bucket attributes to update.
+         *   Only the provided keys are changed; omitted keys are preserved.
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to the updated `Bucket` object.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const updated = await client.storage.buckets.update('bkt_01HXYZ...', {
+         *   description: 'Signed contracts — legal hold applied',
+         *   retention_days: 3650, // 10 years
+         * });
+         * console.log(`Bucket updated: ${updated.name}`);
+         * ```
+         */
+        update: (id: string, attributes: UpdateBucketAttributes, options?: RequestOptions) => Promise<Bucket>;
+    };
+    /**
+     * Sub-namespace for storage file operations.
+     *
+     * Files are tracked as `StorageFile` records with lifecycle states
+     * (`pending_upload`, `active`, `archived`, `pending_deletion`).
+     * Use the `signUpload()` method to create a file, then confirm
+     * the upload once the binary has been written to object storage.
+     */
+    files: {
+        /**
+         * Lists storage files in the current workspace.
+         *
+         * @param options - Optional pagination and request options.
+         * @returns A promise resolving to an array of `StorageFile` objects.
+         *
+         * @example
+         * ```typescript
+         * const files = await client.storage.files.list({ pageSize: 50 });
+         * ```
+         */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<StorageFile[]>;
+        /**
+         * Retrieves a single storage file by ID.
+         *
+         * @param id - The UUID of the file.
+         * @param options - Optional request options.
+         * @returns A promise resolving to the `StorageFile` object.
+         *
+         * @example
+         * ```typescript
+         * const file = await client.storage.files.get('file-uuid');
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<StorageFile>;
+        /**
+         * Archives a file, making it inactive but recoverable.
+         *
+         * @param id - The UUID of the file to archive.
+         * @param options - Optional request options.
+         * @returns A promise resolving to the updated `StorageFile`.
+         */
+        archive: (id: string, options?: RequestOptions) => Promise<StorageFile>;
+        /**
+         * Restores an archived file back to active status.
+         *
+         * @param id - The UUID of the file to restore.
+         * @param options - Optional request options.
+         * @returns A promise resolving to the updated `StorageFile`.
+         */
+        restore: (id: string, options?: RequestOptions) => Promise<StorageFile>;
+        /**
+         * Confirms a presigned upload, transitioning the file to active status.
+         *
+         * @param id - The UUID of the file to confirm.
+         * @param attributes - Optional attributes like `size_bytes` or `checksum`.
+         * @param options - Optional request options.
+         * @returns A promise resolving to the confirmed `StorageFile`.
+         */
+        confirmUpload: (id: string, attributes?: Record<string, unknown>, options?: RequestOptions) => Promise<StorageFile>;
+        /**
+         * Soft-deletes a file, marking it for cleanup.
+         *
+         * @param id - The UUID of the file to soft-delete.
+         * @param options - Optional request options.
+         * @returns A promise resolving to the updated `StorageFile`.
+         */
+        softDelete: (id: string, options?: RequestOptions) => Promise<StorageFile>;
+        /**
+         * Replaces the tags on a file.
+         *
+         * @param id - The UUID of the file to tag.
+         * @param tags - Array of tag strings.
+         * @param options - Optional request options.
+         * @returns A promise resolving to the updated `StorageFile`.
+         */
+        tag: (id: string, tags: string[], options?: RequestOptions) => Promise<StorageFile>;
+        /**
+         * Merges new metadata into the file's existing metadata map.
+         *
+         * @param id - The UUID of the file.
+         * @param newMetadata - Key-value pairs to merge into existing metadata.
+         * @param options - Optional request options.
+         * @returns A promise resolving to the updated `StorageFile`.
+         */
+        updateMetadata: (id: string, newMetadata: Record<string, unknown>, options?: RequestOptions) => Promise<StorageFile>;
+        /**
+         * Finds files matching a given checksum (for deduplication).
+         *
+         * @param checksum - The checksum string to search for.
+         * @param options - Optional request options.
+         * @returns A promise resolving to an array of matching `StorageFile` objects.
+         */
+        byChecksum: (checksum: string, options?: RequestOptions) => Promise<StorageFile[]>;
+        /**
+         * Lists child files for a given parent ID (folder-like hierarchy).
+         *
+         * @param parentId - The UUID of the parent file.
+         * @param options - Optional request options.
+         * @returns A promise resolving to an array of child `StorageFile` objects.
+         */
+        listChildren: (parentId: string, options?: RequestOptions) => Promise<StorageFile[]>;
+        /**
+         * Generate a short-lived presigned download URL for a file.
+         *
+         * Returns a URL that can be used to download the file directly from
+         * object storage (GCS in production, MinIO in dev) without routing
+         * through the application server.
+         *
+         * @param id - The UUID of the file to download.
+         * @param params - Optional parameters (e.g., custom `expires_in` seconds).
+         * @param options - Optional request options (abort signal, custom headers).
+         * @returns A promise resolving to the presigned URL and its expiry.
+         *
+         * @example
+         * ```typescript
+         * const { url, expires_at } = await client.storage.files.requestDownloadUrl(
+         *   'file-uuid',
+         *   { expires_in: 300 }, // 5 minutes
+         * );
+         * // Redirect browser to `url` for direct download
+         * ```
+         */
+        requestDownloadUrl: (id: string, params?: RequestDownloadUrlParams, options?: RequestOptions) => Promise<DownloadUrlResponse>;
+    };
+};
+//# sourceMappingURL=storage.d.ts.map

package/dist/namespaces/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/namespaces/storage.ts"],"names":[],"mappings":"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"}