diff --git a/README.md b/README.md index 4b844d0..0ae3826 100644 --- a/README.md +++ b/README.md @@ -241,13 +241,14 @@ await client.deleteApplication('myapp'); ```typescript await client.updateVersion('myapp', '1.0.0', { releaseNotes: 'Bug fixes', - isActive: true, isEnabled: true, - minimumClientVersion: '0.9.0', - totpCode: '123456', + totpCode: '123456', // required to enable a version when the tenant has TOTP on }); ``` +The API only applies `releaseNotes`, `isEnabled` and `totpCode`. The `isActive` and +`minimumClientVersion` options are deprecated and ignored. + ### Manage Customers ```typescript @@ -358,6 +359,7 @@ interface ApiError { message: string; details?: Record; timestamp?: string; + httpStatus?: number; // set for every non-2xx response } ``` @@ -403,6 +405,24 @@ if (response.success && response.data) { } ``` +Error codes come from two places: + +- **The API's error envelope:** upper case, e.g. `BAD_REQUEST`, `UNAUTHORIZED`, `NOT_FOUND`. +- **The client**, for responses that aren't the envelope (auth middleware, rate limiter, + gateway error pages): lower case and derived from the HTTP status: `bad_request`, + `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, + `http_error`. The client also uses `TIMEOUT` when a request exceeds `timeout`, and + `NETWORK_ERROR` when the request fails or a successful response isn't JSON. + +So compare codes case-insensitively, or check `response.error?.httpStatus`, which is set for +every non-2xx response: + +```typescript +if (response.error?.httpStatus === 429) { + // back off and retry +} +``` + For download operations, errors are thrown as exceptions: ```typescript diff --git a/package-lock.json b/package-lock.json index fe9f8d5..0eb5727 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@bindist/client", - "version": "1.0.1", + "version": "1.0.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@bindist/client", - "version": "1.0.1", + "version": "1.0.2", "license": "MIT", "devDependencies": { "@eslint/js": "^9.0.0", diff --git a/package.json b/package.json index bfd0259..f1f3d41 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@bindist/client", - "version": "1.0.1", + "version": "1.0.2", "description": "TypeScript/JavaScript client for the BinDist API", "main": "dist/index.js", "module": "dist/index.mjs", diff --git a/src/client.ts b/src/client.ts index 4c93d12..253a249 100644 --- a/src/client.ts +++ b/src/client.ts @@ -81,10 +81,14 @@ export class BinDistClient { signal: controller.signal, }); + const text = await response.text(); clearTimeout(timeoutId); - const data = await response.json(); - return data as ApiResponse; + if (!response.ok) { + return errorResponse(response.status, response.statusText, text); + } + + return JSON.parse(text) as ApiResponse; } catch (error) { clearTimeout(timeoutId); @@ -390,6 +394,71 @@ export class BinDistClient { } } +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value); +} + +/** + * Build the response for a non-2xx status. Uses the API's error envelope when + * the body has one; otherwise (auth middleware, rate limiter, gateway HTML + * page, empty body) synthesizes an error from the HTTP status. Either way the + * status is kept in `error.httpStatus`. + */ +function errorResponse( + status: number, + statusText: string, + text: string +): ApiResponse { + let body: unknown; + try { + body = JSON.parse(text); + } catch { + body = undefined; + } + + if (isRecord(body) && isRecord(body.error) && typeof body.error.code === 'string') { + const envelope = body as unknown as ApiResponse; + return { + success: false, + error: { ...envelope.error!, httpStatus: status }, + meta: envelope.meta, + }; + } + + let message = ''; + if (isRecord(body)) { + // Bare {"message": "..."} or {"error": "..."} bodies + if (typeof body.message === 'string') { + message = body.message; + } else if (typeof body.error === 'string') { + message = body.error; + } + } + + return { + success: false, + error: { + code: codeForStatus(status), + message: message || statusText || `HTTP ${status}`, + httpStatus: status, + }, + }; +} + +/** + * Stable lower-case error code for an HTTP status, matching the other BinDist clients. + */ +function codeForStatus(status: number): string { + if (status === 400) return 'bad_request'; + if (status === 401) return 'unauthorized'; + if (status === 403) return 'forbidden'; + if (status === 404) return 'not_found'; + if (status === 409) return 'conflict'; + if (status === 429) return 'rate_limited'; + if (status >= 500) return 'server_error'; + return 'http_error'; +} + /** * Create a new BinDist client instance */ diff --git a/src/types.ts b/src/types.ts index 69ca25f..1391403 100644 --- a/src/types.ts +++ b/src/types.ts @@ -3,13 +3,21 @@ */ /** - * Represents an error returned by the API + * Represents an error returned by the API. + * + * Errors from the API's own error envelope carry upper-case codes such as + * `NOT_FOUND`. Errors from layers in front of the API (auth middleware, rate + * limiters, gateways) don't use the envelope; for those the client derives a + * lower-case code from the HTTP status (`unauthorized`, `rate_limited`, + * `server_error`, ...). Compare codes case-insensitively, or use `httpStatus`. */ export interface ApiError { code: string; message: string; details?: Record; timestamp?: string; + /** HTTP status of the response; set for every non-2xx response. */ + httpStatus?: number; } /** @@ -94,9 +102,12 @@ export interface GetDownloadInfoOptions { */ export interface UpdateVersionOptions { releaseNotes?: string | null; + /** @deprecated Ignored by the API; only `releaseNotes`, `isEnabled` and `totpCode` are applied. */ isActive?: boolean; isEnabled?: boolean; + /** @deprecated Ignored by the API; only `releaseNotes`, `isEnabled` and `totpCode` are applied. */ minimumClientVersion?: string; + /** 6-digit TOTP code; required when setting `isEnabled: true` on a tenant with TOTP enabled. */ totpCode?: string; }