@giveitsmaller/sdk 0.2.1 → 0.2.3

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import type { UploadResponse, WorkflowCreateResponse, WorkflowStatusResponse, WorkflowDownloadResponse, MetadataResponse, OperationsSchemaResponse, RetryResponse } from '@giveitsmaller/contracts/openapi';
 import type { GislClientConfig, GislSseEvent, UploadOptions, WaitOptions, WorkflowCreatePayload } from './types.js';
+export declare const DEFAULT_MULTIPART_FIRST_CHUNK_SIZE: number;
 export declare class GislClient {
     private readonly baseUrl;
     private readonly headers;
@@ -18,6 +19,17 @@ export declare class GislClient {
      */
     uploadFile(file: string | Blob, options?: UploadOptions): Promise<UploadResponse>;
     private singleUpload;
+    /**
+     * Direct-to-S3 multipart upload for files above the threshold.
+     *
+     * The /multipart/complete response (MultipartCompleteResponse) only carries
+     * { upload_id, status }. The server's upload_id is the same UUID callers
+     * pass as file_id to POST /api/workflows — so fileId is synthesised from
+     * upload_id and a full UploadResponse is returned to keep the public
+     * uploadFile() API uniform across single and multipart paths. The mimeType
+     * comes from the initiate response's first-chunk detection; for authoritative
+     * post-upload metadata callers should use getMetadata(fileId).
+     */
     private multipartUpload;
     /**
      * Create a new workflow.

package/dist/client.js

@@ -1,11 +1,17 @@
 import { readFileSync, statSync } from 'node:fs';
 import { basename } from 'node:path';
-import { UploadResponseFromJSON, MultipartInitiateResponseFromJSON, WorkflowCreateResponseFromJSON, WorkflowStatusResponseFromJSON, WorkflowDownloadResponseFromJSON, MetadataResponseFromJSON, OperationsSchemaResponseFromJSON, RetryResponseFromJSON, WorkflowStatus, } from '@giveitsmaller/contracts/openapi';
+import { UploadResponseFromJSON, MultipartInitiateResponseFromJSON, MultipartCompleteResponseFromJSON, WorkflowCreateResponseFromJSON, WorkflowStatusResponseFromJSON, WorkflowDownloadResponseFromJSON, MetadataResponseFromJSON, OperationsSchemaResponseFromJSON, RetryResponseFromJSON, WorkflowStatus, } from '@giveitsmaller/contracts/openapi';
 import { GislApiError, GislError, GislTimeoutError, GislValidationError } from './errors.js';
 import { parseSseStream } from './sse.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MULTIPART_THRESHOLD = 10 * 1024 * 1024; // 10 MB
 const DEFAULT_MULTIPART_CONCURRENCY = 4;
+// Fixed per contract (compression_contracts/openapi/api.yaml:134). The server
+// uses the first chunk for MIME detection + throughput measurement and stores
+// it as S3 multipart part 1. Must NOT be derived from multipartThreshold —
+// that is the "use multipart above this size" routing threshold, a separate
+// concept. Conflating them caused the /api/uploads/multipart/initiate 413.
+export const DEFAULT_MULTIPART_FIRST_CHUNK_SIZE = 8 * 1024 * 1024; // 8 MB
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_POLL_TIMEOUT_MS = 300_000; // 5 min
 const TERMINAL_STATUSES = new Set([
@@ -13,6 +19,13 @@ const TERMINAL_STATUSES = new Set([
     WorkflowStatus.failed,
     WorkflowStatus.partially_failed,
 ]);
+function isValidationDetails(value) {
+    return (Array.isArray(value) &&
+        value.every((el) => typeof el === 'object' &&
+            el !== null &&
+            typeof el.field === 'string' &&
+            typeof el.message === 'string'));
+}
 export class GislClient {
     baseUrl;
     headers;
@@ -22,7 +35,10 @@ export class GislClient {
     constructor(config) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
         this.timeoutMs = config.timeout ?? DEFAULT_TIMEOUT_MS;
-        this.multipartThreshold = config.multipartThreshold ?? DEFAULT_MULTIPART_THRESHOLD;
+        // Floor the threshold at the first-chunk size: the multipart initiate
+        // must always carry an 8MB chunk, so routing a sub-8MB file into the
+        // multipart path would violate the contract.
+        this.multipartThreshold = Math.max(config.multipartThreshold ?? DEFAULT_MULTIPART_THRESHOLD, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE);
         this.multipartConcurrency = config.multipartConcurrency ?? DEFAULT_MULTIPART_CONCURRENCY;
         this.headers = { ...config.headers };
         if (config.apiKey) {
@@ -69,27 +85,34 @@ export class GislClient {
         return this.handleResponse(response, path, opts.deserialize);
     }
     async handleResponse(response, path, deserialize) {
-        const contentType = response.headers.get('content-type') ?? '';
-        if (!contentType.includes('application/json')) {
+        const contentType = (response.headers.get('content-type') ?? '').toLowerCase();
+        const isJsonContent = contentType.includes('application/json') || contentType.includes('+json');
+        if (!isJsonContent) {
             if (!response.ok) {
-                throw new GislApiError(response.status, `Non-JSON error from ${path}`);
+                throw new GislApiError(response.status, 'Non-JSON response', path);
             }
             return undefined;
         }
-        const json = await response.json();
+        let json;
+        try {
+            json = await response.json();
+        }
+        catch {
+            throw new GislApiError(response.status, 'Invalid JSON response', path);
+        }
         // Schema endpoint returns raw JSON (no envelope)
         if (path === '/api/operations/schema') {
             if (!response.ok) {
-                throw new GislApiError(response.status, json.error ?? 'Unknown error');
+                throw new GislApiError(response.status, json.error ?? 'Unknown error', path);
             }
             return deserialize ? deserialize(json) : json;
         }
         // Standard envelope: { success, data } or { success, error, details }
         if (!response.ok || json.success === false) {
-            if (json.details && Array.isArray(json.details)) {
-                throw new GislValidationError(response.status, json.error ?? 'Validation error', json.details);
+            if (isValidationDetails(json.details)) {
+                throw new GislValidationError(response.status, json.error ?? 'Validation error', json.details, path);
             }
-            throw new GislApiError(response.status, json.error ?? 'Unknown error');
+            throw new GislApiError(response.status, json.error ?? 'Unknown error', path, json.details);
         }
         const data = json.data ?? json;
         return deserialize ? deserialize(data) : data;
@@ -134,14 +157,25 @@ export class GislClient {
             deserialize: UploadResponseFromJSON,
         });
     }
+    /**
+     * Direct-to-S3 multipart upload for files above the threshold.
+     *
+     * The /multipart/complete response (MultipartCompleteResponse) only carries
+     * { upload_id, status }. The server's upload_id is the same UUID callers
+     * pass as file_id to POST /api/workflows — so fileId is synthesised from
+     * upload_id and a full UploadResponse is returned to keep the public
+     * uploadFile() API uniform across single and multipart paths. The mimeType
+     * comes from the initiate response's first-chunk detection; for authoritative
+     * post-upload metadata callers should use getMetadata(fileId).
+     */
     async multipartUpload(blob, fileName, totalSize, options) {
         // Step 1: Initiate with first chunk
-        const firstChunkSize = Math.min(totalSize, this.multipartThreshold);
+        const firstChunkSize = Math.min(totalSize, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE);
         const firstChunk = blob.slice(0, firstChunkSize);
         const initiateForm = new FormData();
-        initiateForm.append('chunk', firstChunk, fileName);
-        initiateForm.append('original_name', fileName);
-        initiateForm.append('total_size_bytes', totalSize.toString());
+        initiateForm.append('file', firstChunk, fileName);
+        initiateForm.append('filename', fileName);
+        initiateForm.append('total_size', totalSize.toString());
         const initResponse = await this.request('POST', '/api/uploads/multipart/initiate', {
             body: initiateForm,
             json: false,
@@ -183,15 +217,27 @@ export class GislClient {
             }
         });
         await Promise.all(workers);
-        // Step 3: Complete multipart upload
+        // Step 3: Complete multipart upload.
         etags.sort((a, b) => a.part_number - b.part_number);
-        return this.request('POST', '/api/uploads/multipart/complete', {
+        const completeResp = await this.request('POST', '/api/uploads/multipart/complete', {
             body: {
-                file_id: initResponse.fileId,
+                upload_id: initResponse.uploadId,
                 parts: etags,
             },
-            deserialize: UploadResponseFromJSON,
+            deserialize: MultipartCompleteResponseFromJSON,
         });
+        // Defensive: the status enum currently has only 'completed', but guard
+        // against future expansion so an unexpected terminal state doesn't pass
+        // as a successful upload.
+        if (completeResp.status !== 'completed') {
+            throw new GislError(`Multipart upload completed with unexpected status: ${completeResp.status}`);
+        }
+        return {
+            fileId: completeResp.uploadId,
+            originalName: fileName,
+            mimeType: initResponse.mimeType,
+            sizeBytes: blob.size,
+        };
     }
     // -----------------------------------------------------------------------
     // Workflows
@@ -244,9 +290,10 @@ export class GislClient {
      * Stream SSE events for a workflow. Returns an async iterable.
      */
     async streamEvents(workflowId) {
-        const response = await this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/events`, { rawResponse: true });
+        const eventsPath = `/api/workflows/${encodeURIComponent(workflowId)}/events`;
+        const response = await this.request('GET', eventsPath, { rawResponse: true });
         if (!response.ok) {
-            await this.handleResponse(response, `/api/workflows/${workflowId}/events`);
+            await this.handleResponse(response, eventsPath);
         }
         return parseSseStream(response);
     }

package/dist/errors.d.ts

@@ -4,7 +4,9 @@ export declare class GislError extends Error {
 export declare class GislApiError extends GislError {
     readonly statusCode: number;
     readonly errorMessage: string;
-    constructor(statusCode: number, errorMessage: string);
+    readonly path?: string;
+    readonly details?: unknown;
+    constructor(statusCode: number, errorMessage: string, path?: string, details?: unknown);
 }
 export declare class GislValidationError extends GislApiError {
     readonly details: Array<{
@@ -14,7 +16,7 @@ export declare class GislValidationError extends GislApiError {
     constructor(statusCode: number, errorMessage: string, details: Array<{
         field: string;
         message: string;
-    }>);
+    }>, path?: string);
 }
 export declare class GislTimeoutError extends GislError {
     constructor(message: string);

package/dist/errors.js

@@ -7,19 +7,24 @@ export class GislError extends Error {
 export class GislApiError extends GislError {
     statusCode;
     errorMessage;
-    constructor(statusCode, errorMessage) {
-        super(`API error ${statusCode}: ${errorMessage}`);
+    path;
+    details;
+    constructor(statusCode, errorMessage, path, details) {
+        const prefix = path
+            ? `API error ${statusCode} at ${path}`
+            : `API error ${statusCode}`;
+        super(`${prefix}: ${errorMessage}`);
         this.name = 'GislApiError';
         this.statusCode = statusCode;
         this.errorMessage = errorMessage;
+        this.path = path;
+        this.details = details;
     }
 }
 export class GislValidationError extends GislApiError {
-    details;
-    constructor(statusCode, errorMessage, details) {
-        super(statusCode, errorMessage);
+    constructor(statusCode, errorMessage, details, path) {
+        super(statusCode, errorMessage, path, details);
         this.name = 'GislValidationError';
-        this.details = details;
     }
 }
 export class GislTimeoutError extends GislError {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { GislClient } from './client.js';
+export { GislClient, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE } from './client.js';
 export { verifyWebhook } from './webhook.js';
 export { parseSseStream } from './sse.js';
 export type { GislClientConfig, GislSseEvent, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, FileJobPayload, SourceJobPayload, InputsJobPayload, JobDefinitionPayload, } from './types.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 // SDK classes and functions
-export { GislClient } from './client.js';
+export { GislClient, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE } from './client.js';
 export { verifyWebhook } from './webhook.js';
 export { parseSseStream } from './sse.js';
 export { fileJob, sourceJob, inputsJob } from './types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
   "license": "MIT",
   "type": "module",
@@ -19,12 +19,13 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@giveitsmaller/contracts": "^0.1.0"
+    "@giveitsmaller/contracts": "^0.2.3"
   },
   "devDependencies": {
     "@types/node": "^22",
     "typescript": "^5.7",
-    "vitest": "^3.1"
+    "vitest": "^3.1",
+    "yaml": "^2.6"
   },
   "scripts": {
     "build": "tsc",