@oasis-path/gamma-sdk 1.0.4 → 1.0.5

package/README.md

@@ -136,14 +136,26 @@ console.log('Expires at:', result.expiresAt);
 
 ### View File by Token
 
-Access a file using a presigned token (no API key required):
+Access a file using a presigned token (no API key required). Returns the file data along with response headers including caching information:
 
 ```typescript
-const fileData = await client.viewFileByToken('presigned-token-here');
+const result = await client.viewFileByToken('presigned-token-here');
 
-// Handle the file data as needed
-const buffer = Buffer.from(fileData);
+// Access file data
+const buffer = Buffer.from(result.data);
 fs.writeFileSync('./viewed-file.pdf', buffer);
+
+// Access cache headers for optimization
+console.log('Content Type:', result.headers.contentType);
+console.log('File Size:', result.headers.contentLength);
+console.log('ETag:', result.headers.etag); // For cache validation
+console.log('Cache Control:', result.headers.cacheControl);
+console.log('Cloudflare Cache Tag:', result.headers.cfCacheTag); // File ID for consistent caching
+
+// In browser, use the headers to implement client-side caching
+if (result.headers.etag) {
+  localStorage.setItem(`file-etag-${result.headers.cfCacheTag}`, result.headers.etag);
+}
 ```
 
 ## API Reference
@@ -232,14 +244,22 @@ Generate a presigned URL for temporary file access.
 
 **API Key Permissions Required:** `read`, `write`, or `admin`
 
-##### `viewFileByToken(token: string): Promise<ArrayBuffer>`
+##### `viewFileByToken(token: string): Promise<ViewFileByTokenResult>`
 
-Access a file using a presigned token (no API key required).
+Access a file using a presigned token (no API key required). Returns file data along with response headers including caching information.
 
 **Parameters:**
 - `token` - Presigned token from `generatePresignedUrl`
 
-**Returns:** File data as ArrayBuffer
+**Returns:** Object containing:
+- `data` - File data as ArrayBuffer
+- `headers` - Response headers including:
+  - `contentType` - MIME type of the file
+  - `contentLength` - Size of the file in bytes
+  - `contentDisposition` - Content disposition header (inline)
+  - `etag` - Entity tag for cache validation (based on file ID)
+  - `cacheControl` - Cache control directives (1 year immutable)
+  - `cfCacheTag` - Cloudflare cache tag (file ID for consistent caching across tokens)
 
 **API Key Permissions Required:** None (uses token authentication)
 
@@ -260,6 +280,7 @@ import {
   PresignedUrlOptions,
   PresignedUrlResponse,
   DownloadFileResult,
+  ViewFileByTokenResult,
   ApiErrorResponse
 } from '@gamma/files-sdk';
 ```

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { GammaFilesClientConfig, UploadFileOptions, UploadFileResponse, ListFilesResponse, FileMetadataResponse, DeleteFileResponse, PresignedUrlOptions, PresignedUrlResponse } from './types';
+import { GammaFilesClientConfig, UploadFileOptions, UploadFileResponse, ListFilesResponse, FileMetadataResponse, DeleteFileResponse, PresignedUrlOptions, PresignedUrlResponse, ViewFileByTokenResult } from './types';
 export declare class GammaFilesClient {
     private baseUrl;
     private apiKey;
@@ -9,6 +9,6 @@ export declare class GammaFilesClient {
     deleteFile(fileId: string): Promise<DeleteFileResponse>;
     getFileMetadata(fileId: string): Promise<FileMetadataResponse>;
     generatePresignedUrl(options: PresignedUrlOptions): Promise<PresignedUrlResponse>;
-    viewFileByToken(token: string): Promise<ArrayBuffer>;
+    viewFileByToken(token: string): Promise<ViewFileByTokenResult>;
     private request;
 }

package/dist/methods/generatePresignedUrl.js

@@ -3,8 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generatePresignedUrl = generatePresignedUrl;
 async function generatePresignedUrl(options, request) {
     const url = '/api/files/presigned-url';
+    const payload = {
+        ...options,
+        maxUsageCount: options.maxUsageCount ?? 1
+    };
     return request('POST', url, {
-        body: JSON.stringify(options),
+        body: JSON.stringify(payload),
         headers: {
             'Content-Type': 'application/json',
         },

package/dist/methods/request.d.ts

@@ -3,4 +3,5 @@ export declare function makeRequest<T>(method: string, path: string, baseUrl: st
     headers?: Record<string, string>;
     binary?: boolean;
     skipAuth?: boolean;
+    includeHeaders?: boolean;
 }): Promise<T>;

package/dist/methods/request.js

@@ -78,7 +78,24 @@ async function makeRequest(method, path, baseUrl, apiKey, options = {}) {
                     return;
                 }
                 if (options.binary) {
-                    resolve(buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength));
+                    const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+                    if (options.includeHeaders) {
+                        const result = {
+                            data: arrayBuffer,
+                            headers: {
+                                contentType: res.headers['content-type'] || '',
+                                contentLength: parseInt(res.headers['content-length'] || '0', 10),
+                                contentDisposition: res.headers['content-disposition'] || '',
+                                etag: res.headers['etag'],
+                                cacheControl: res.headers['cache-control'],
+                                cfCacheTag: res.headers['cf-cache-tag'],
+                            }
+                        };
+                        resolve(result);
+                    }
+                    else {
+                        resolve(arrayBuffer);
+                    }
                 }
                 else {
                     const data = JSON.parse(responseText);

package/dist/methods/viewFileByToken.d.ts

@@ -1 +1,2 @@
-export declare function viewFileByToken(token: string, request: <T>(method: string, path: string, options?: any) => Promise<T>): Promise<ArrayBuffer>;
+import { ViewFileByTokenResult } from '../types';
+export declare function viewFileByToken(token: string, request: <T>(method: string, path: string, options?: any) => Promise<T>): Promise<ViewFileByTokenResult>;

package/dist/methods/viewFileByToken.js

@@ -5,6 +5,7 @@ async function viewFileByToken(token, request) {
     const url = `/api/files/view/${token}`;
     return request('GET', url, {
         binary: true,
-        skipAuth: true
+        skipAuth: true,
+        includeHeaders: true
     });
 }

package/dist/types.d.ts

@@ -37,6 +37,7 @@ export interface DeleteFileResponse {
 export interface PresignedUrlOptions {
     fileId: string;
     expiresIn?: number;
+    maxUsageCount?: number;
 }
 export interface PresignedUrlResponse {
     success: true;
@@ -48,6 +49,17 @@ export interface DownloadFileResult {
     file: FileMetadata;
     data: ArrayBuffer;
 }
+export interface ViewFileByTokenResult {
+    data: ArrayBuffer;
+    headers: {
+        contentType: string;
+        contentLength: number;
+        contentDisposition: string;
+        etag?: string;
+        cacheControl?: string;
+        cfCacheTag?: string;
+    };
+}
 export interface ApiErrorResponse {
     success: false;
     error: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oasis-path/gamma-sdk",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "TypeScript SDK for Gamma Files API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",