@attlaz/client 1.111.0 → 1.113.0

package/dist/Http/HttpClient.js

@@ -33,7 +33,7 @@ export class HttpClient {
                     clientError.response = {
                         status: rawResponse.status,
                         statusText,
-                        data: await rawResponse.json(),
+                        data: JSON.parse(Buffer.from(await rawResponse.arrayBuffer()).toString('utf8')),
                     };
                 }
                 catch {
@@ -45,13 +45,11 @@ export class HttpClient {
             rawResponse.headers.forEach((value, header) => {
                 httpResponse.headers[header] = value;
             });
-            const contentType = rawResponse.headers.get('content-type');
-            if (contentType !== null && contentType.includes('application/json')) {
-                httpResponse.body = await rawResponse.json();
-            }
-            else {
-                httpResponse.body = await rawResponse.text();
-            }
+            // Bytes, never an interpretation. The caller already knows what it asked for — an
+            // endpoint supplies a parser, a blob read wants the bytes — so sniffing the content type
+            // here would be a second, weaker answer to a question already answered. It was also
+            // lossy: the old `text()` fallback UTF-8-decoded binary, turning 10 bytes into 16.
+            httpResponse.body = Buffer.from(await rawResponse.arrayBuffer());
             return httpResponse;
         }
         catch (error) {

package/dist/Http/HttpClientResponse.d.ts

@@ -1,8 +1,19 @@
 import { Headers } from './Data/Headers.js';
+/**
+ * A response as it came off the wire. `body` is always bytes — the transport does not interpret,
+ * because the caller already knows what it asked for. Use `getJson()` or `getBytes()` to say which.
+ */
 export declare class HttpClientResponse {
     status: number;
     statusText: string;
-    body: any | null;
+    body: Buffer | null;
     headers: Headers;
     constructor(status: number, statusText: string);
+    /** The raw bytes, empty when the response had no body. */
+    getBytes(): Buffer;
+    /**
+     * The body parsed as JSON, or null when there was none — a 204 and a DELETE that answers empty
+     * are normal, and `JSON.parse('')` throws.
+     */
+    getJson<T>(): T | null;
 }

package/dist/Http/HttpClientResponse.js

@@ -1,3 +1,7 @@
+/**
+ * A response as it came off the wire. `body` is always bytes — the transport does not interpret,
+ * because the caller already knows what it asked for. Use `getJson()` or `getBytes()` to say which.
+ */
 export class HttpClientResponse {
     status;
     statusText;
@@ -7,4 +11,19 @@ export class HttpClientResponse {
         this.status = status;
         this.statusText = statusText;
     }
+    /** The raw bytes, empty when the response had no body. */
+    getBytes() {
+        return this.body ?? Buffer.alloc(0);
+    }
+    /**
+     * The body parsed as JSON, or null when there was none — a 204 and a DELETE that answers empty
+     * are normal, and `JSON.parse('')` throws.
+     */
+    getJson() {
+        const bytes = this.getBytes();
+        if (bytes.length === 0) {
+            return null;
+        }
+        return JSON.parse(bytes.toString('utf8'));
+    }
 }

package/dist/Http/Transport/DirectTransport.d.ts

@@ -32,6 +32,7 @@ export declare class DirectTransport implements ITransport {
     private parseErrorHandler;
     constructor(defaultBaseUrl: string, sessionPayload: string, sessionSignature: string, routes?: DirectTransportRoute[]);
     request<T>(action: string, parameters?: Parameters, method?: string, _signWithOauthToken?: boolean): Promise<T>;
+    requestBytes(action: string, parameters?: Parameters, method?: string, _signWithOauthToken?: boolean, headers?: Record<string, string>): Promise<Buffer>;
     private resolveClient;
     isDebugEnabled(): boolean;
     setParseErrorHandler(handler: ParseErrorHandler | null): void;

package/dist/Http/Transport/DirectTransport.js

@@ -44,6 +44,10 @@ export class DirectTransport {
         // Always call without OAuth signing — authentication is via the signed session headers
         return await client.request(action, parameters, method, false);
     }
+    async requestBytes(action, parameters = null, method = 'GET', _signWithOauthToken = true, headers = {}) {
+        const client = this.resolveClient(action);
+        return await client.requestBytes(action, parameters, method, false, headers);
+    }
     resolveClient(action) {
         for (const route of this.sortedRoutes) {
             if (action.startsWith(route.prefix)) {

package/dist/Http/Transport/ITransport.d.ts

@@ -7,6 +7,8 @@ import { Parameters } from '../Data/Parameters.js';
 export type ParseErrorHandler = (message: string, context: Record<string, unknown>) => void;
 export interface ITransport {
     request: <T>(action: string, parameters: Parameters, method: string, signWithOauthToken: boolean) => Promise<T>;
+    /** The response bytes, undecoded — for resources a JSON round trip would inflate or destroy. */
+    requestBytes: (action: string, parameters: Parameters, method: string, signWithOauthToken: boolean, headers?: Record<string, string>) => Promise<Buffer>;
     isDebugEnabled: () => boolean;
     reportParseError: (message: string, context: Record<string, unknown>) => void;
     setParseErrorHandler: (handler: ParseErrorHandler | null) => void;

package/dist/Http/Transport/OAuthClient.d.ts

@@ -48,6 +48,11 @@ export declare class OAuthClient implements ITransport {
      */
     private requestToken;
     isTokenExpired(): boolean;
+    /**
+     * Like `request`, but asks for and returns the raw bytes. For a resource that has a binary
+     * representation — a stored item — where decoding would destroy it.
+     */
+    requestBytes(action: string, parameters?: Parameters, method?: string, signWithOauthToken?: boolean, headers?: Record<string, string>): Promise<Buffer>;
     request<T>(action: string, parameters?: Parameters, method?: string, signWithOauthToken?: boolean): Promise<T>;
     isAuthenticated(): boolean;
     getToken(): OAuthClientToken | null;

package/dist/Http/Transport/OAuthClient.js

@@ -219,6 +219,25 @@ export class OAuthClient {
         }
         return OAuthClientToken.isExpired(this.oauthClientToken);
     }
+    /**
+     * Like `request`, but asks for and returns the raw bytes. For a resource that has a binary
+     * representation — a stored item — where decoding would destroy it.
+     */
+    async requestBytes(action, parameters = null, method = 'GET', signWithOauthToken = true, headers = {}) {
+        if (signWithOauthToken) {
+            await this.ensureAccessToken();
+            if (this.oauthClientToken === null) {
+                throw new ClientError('Unable to perform request, access token not provided', HttpStatus.HTTP_UNAUTHORIZED);
+            }
+        }
+        const requestData = this.createRequestData(action, parameters, method, signWithOauthToken);
+        requestData.setHeader('Accept', 'application/octet-stream');
+        for (const [name, value] of Object.entries(headers)) {
+            requestData.setHeader(name, value);
+        }
+        const response = await HttpClient.request(requestData, this.options.timeoutMs);
+        return response.getBytes();
+    }
     async request(action, parameters = null, method = 'GET', signWithOauthToken = true) {
         if (signWithOauthToken) {
             // Token-first, credentials-as-fallback (mirrors the PHP client): use a valid token as-is,
@@ -235,7 +254,7 @@ export class OAuthClient {
         }
         try {
             const response = await HttpClient.request(requestData, this.options.timeoutMs);
-            return response.body;
+            return response.getJson();
         }
         catch (error) {
             if (!(error instanceof ClientError)) {
@@ -367,20 +386,33 @@ export class OAuthClient {
         const url = this.getApiEndpointUrl(action);
         let requestData = new HttpClientRequest(url, method);
         requestData.headers = this.getDefaultHeaders();
+        // Stated explicitly, even though JSON is what the API returns by default today. The server
+        // plans to make bytes the default once no request arrives without an Accept, and a silent
+        // client is indistinguishable from one that did not care — which is what makes that flip
+        // unsafe. An endpoint wanting another representation overrides this afterwards.
+        requestData.setHeader('Accept', 'application/json');
         if (this.version !== null) {
             requestData.setHeader('Attlaz-API-Version', this.version);
         }
         if ((method === 'POST' || method === 'DELETE' || method === 'PUT' || method === 'PATCH') && parameters !== null && parameters !== undefined) {
-            if (typeof parameters === 'object') {
+            // A Buffer is the payload, not something to serialise. Stringifying one yields
+            // {"type":"Buffer","data":[…]} — larger than the bytes and not what any reader expects.
+            if (Buffer.isBuffer(parameters)) {
+                requestData.body = parameters;
+                requestData.setHeader('Content-Type', 'application/octet-stream');
+            }
+            else if (typeof parameters === 'object') {
                 requestData.body = JsonSerializable.stringify(parameters);
+                requestData.setJsonHeader();
             }
             else if (typeof parameters === 'string') {
                 requestData.body = parameters;
+                requestData.setJsonHeader();
             }
             else {
                 console.error('Unknown parameter type: ' + typeof parameters);
+                requestData.setJsonHeader();
             }
-            requestData.setJsonHeader();
         }
         if (method === 'GET' && parameters !== null && parameters !== undefined) {
             const params = parameters;

package/dist/Service/Endpoint.d.ts

@@ -15,6 +15,13 @@ export declare abstract class Endpoint {
     private prepareParameters;
     private formatParameters;
     private formatKey;
+    /** Raw response bytes for this action — see `ITransport.requestBytes`. */
+    requestBytes(action: string, parameters?: Parameters, method?: string, signWithOauthToken?: boolean, headers?: Record<string, string>): Promise<Buffer>;
+    /**
+     * Send raw bytes as the request body. Metadata rides headers because the body IS the value —
+     * there is no envelope left to put it in.
+     */
+    requestBinary(action: string, value: Buffer, headers?: Record<string, string>): Promise<void>;
     requestCollection<T>(action: string | QueryString, parser: (input: any) => T, parameters?: Parameters, method?: string, signWithOauthToken?: boolean): Promise<CollectionResult<T>>;
     requestObject<T>(action: string | QueryString, parameters: Parameters | undefined, parser: (input: Record<string, any>) => T, method?: string, signWithOauthToken?: boolean): Promise<ObjectResult<T>>;
     private toApiError;

package/dist/Service/Endpoint.js

@@ -79,6 +79,17 @@ export class Endpoint {
         }
         return formattedKey;
     }
+    /** Raw response bytes for this action — see `ITransport.requestBytes`. */
+    async requestBytes(action, parameters = null, method = 'GET', signWithOauthToken = true, headers = {}) {
+        return await this.httpClient.requestBytes(action, parameters, method, signWithOauthToken, headers);
+    }
+    /**
+     * Send raw bytes as the request body. Metadata rides headers because the body IS the value —
+     * there is no envelope left to put it in.
+     */
+    async requestBinary(action, value, headers = {}) {
+        await this.httpClient.requestBytes(action, value, 'POST', true, headers);
+    }
     async requestCollection(action, parser, parameters = null, method = 'GET', signWithOauthToken = true) {
         parameters = this.prepareParameters(parameters);
         if (action instanceof QueryString) {

package/dist/Service/StorageEndpoint.d.ts

@@ -15,6 +15,25 @@ export declare class StorageEndpoint extends Endpoint {
     clearPool(projectEnvironmentId: string, storageType: StorageType, bucketKey: string): Promise<boolean>;
     getItem(projectEnvironmentId: string, storageType: StorageType, bucketKey: string, storageItemKey: string): Promise<StorageItem | null>;
     getBucketItem(storageBucketId: string, storageItemKey: string): Promise<StorageItem | null>;
+    /**
+     * The item's bytes, without decoding. Use for anything binary — an image, an archive — where the
+     * JSON envelope would either inflate it (base64) or destroy it (a UTF-8 decode replaces every
+     * invalid sequence, so bytes do not survive the round trip).
+     */
+    /**
+     * Whether an item exists, without transferring it. Backed by HEAD, so a content-addressed check
+     * ("do I already have these bytes?") costs headers rather than the whole object.
+     */
+    hasItem(projectEnvironmentId: string, storageType: StorageType, bucketKey: string, storageItemKey: string): Promise<boolean>;
+    getItemBytes(projectEnvironmentId: string, storageType: StorageType, bucketKey: string, storageItemKey: string): Promise<Buffer>;
+    /**
+     * Store raw bytes. Metadata travels as headers, since the body is the value.
+     *
+     * Pass `contentType` for anything that will be served to a browser — the CDN reads it back as the
+     * response `Content-Type`, and without it an image is delivered as `application/octet-stream`,
+     * which downloads rather than renders.
+     */
+    setItemBytes(projectEnvironmentId: string, storageType: StorageType, bucketKey: string, storageItemKey: string, value: Buffer, expiration?: Date | null, contentType?: string | null): Promise<void>;
     setItem(projectEnvironmentId: string, storageType: StorageType, bucketKey: string, storageItem: StorageItem): Promise<StorageItem>;
     deleteItem(projectEnvironmentId: string, storageType: StorageType, bucketKey: string, storageItemKey: string): Promise<boolean>;
 }

package/dist/Service/StorageEndpoint.js

@@ -3,6 +3,8 @@ import { StorageInformation } from '../Model/Storage/StorageInformation.js';
 import { StorageItem } from '../Model/Storage/StorageItem.js';
 import { StorageItemInformation } from '../Model/Storage/StorageItemInformation.js';
 import { QueryString } from '../Http/Data/QueryString.js';
+import { ClientError } from '../Http/ClientError.js';
+import { HttpStatus } from '../Http/HttpStatus.js';
 import { Endpoint } from './Endpoint.js';
 export class StorageEndpoint extends Endpoint {
     async getInformation(projectEnvironmentId, storageType) {
@@ -93,6 +95,50 @@ export class StorageEndpoint extends Endpoint {
             throw ex;
         }
     }
+    /**
+     * The item's bytes, without decoding. Use for anything binary — an image, an archive — where the
+     * JSON envelope would either inflate it (base64) or destroy it (a UTF-8 decode replaces every
+     * invalid sequence, so bytes do not survive the round trip).
+     */
+    /**
+     * Whether an item exists, without transferring it. Backed by HEAD, so a content-addressed check
+     * ("do I already have these bytes?") costs headers rather than the whole object.
+     */
+    async hasItem(projectEnvironmentId, storageType, bucketKey, storageItemKey) {
+        const cmd = path('/projectenvironments/:projectEnvironmentId/storage/:storageType/:bucketKey/items/:key', { projectEnvironmentId, storageType, bucketKey, key: storageItemKey });
+        try {
+            await this.requestBytes(cmd, null, 'HEAD');
+            return true;
+        }
+        catch (error) {
+            if (ClientError.statusOf(error) === HttpStatus.HTTP_NOTFOUND) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async getItemBytes(projectEnvironmentId, storageType, bucketKey, storageItemKey) {
+        const cmd = path('/projectenvironments/:projectEnvironmentId/storage/:storageType/:bucketKey/items/:key', { projectEnvironmentId, storageType, bucketKey, key: storageItemKey });
+        return await this.requestBytes(cmd);
+    }
+    /**
+     * Store raw bytes. Metadata travels as headers, since the body is the value.
+     *
+     * Pass `contentType` for anything that will be served to a browser — the CDN reads it back as the
+     * response `Content-Type`, and without it an image is delivered as `application/octet-stream`,
+     * which downloads rather than renders.
+     */
+    async setItemBytes(projectEnvironmentId, storageType, bucketKey, storageItemKey, value, expiration = null, contentType = null) {
+        const cmd = path('/projectenvironments/:projectEnvironmentId/storage/:storageType/:bucketKey/items/:key', { projectEnvironmentId, storageType, bucketKey, key: storageItemKey });
+        const headers = {};
+        if (expiration !== null) {
+            headers['X-Attlaz-Expiration'] = expiration.toISOString();
+        }
+        if (contentType !== null) {
+            headers['X-Attlaz-Content-Type'] = contentType;
+        }
+        await this.requestBinary(cmd, value, headers);
+    }
     async setItem(projectEnvironmentId, storageType, bucketKey, storageItem) {
         const cmd = path('/projectenvironments/:projectEnvironmentId/storage/:storageType/:bucketKey/items/:key', { projectEnvironmentId, storageType, bucketKey, key: storageItem.key });
         try {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.110.0";
+export declare const VERSION = "1.112.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "1.110.0";
+export const VERSION = "1.112.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attlaz/client",
-  "version": "1.111.0",
+  "version": "1.113.0",
   "description": "Javascript Client to access Attlaz API",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",