@heroku/heroku-fetch 0.2.5 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -55,14 +55,31 @@ const dataClient = new HerokuApiClient({
|
|
|
55
55
|
token: 'your_token',
|
|
56
56
|
});
|
|
57
57
|
|
|
58
|
-
//
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
58
|
+
// The data client's host comes from HEROKU_DATA_HOST, then
|
|
59
|
+
// HEROKU_POSTGRESQL_HOST, then postgres-api.heroku.com. A bare hostname
|
|
60
|
+
// gets https://. An explicit baseUrl takes precedence.
|
|
61
|
+
//
|
|
62
|
+
// This applies to every service host variable below: a plain http:// value
|
|
63
|
+
// is accepted only for localhost, 127.0.0.1 or [::1]. Any other http:// host
|
|
64
|
+
// throws when the client is built, so the token is never sent unencrypted.
|
|
65
|
+
|
|
66
|
+
// Metrics. The host comes from HEROKU_METRICS_HOST, then
|
|
67
|
+
// api.metrics.heroku.com. An explicit baseUrl takes precedence.
|
|
68
|
+
const metricsClient = new HerokuApiClient({
|
|
69
|
+
service: 'metrics',
|
|
62
70
|
token: 'your_token',
|
|
63
71
|
});
|
|
64
72
|
|
|
65
|
-
//
|
|
73
|
+
// Notifications (telex) and repositories (kolkrabbi). Their hosts come from
|
|
74
|
+
// HEROKU_NOTIFICATIONS_HOST / HEROKU_REPOSITORIES_HOST, then telex.heroku.com /
|
|
75
|
+
// kolkrabbi.heroku.com. Neither sends a default Accept header.
|
|
76
|
+
const notificationsClient = new HerokuApiClient({
|
|
77
|
+
service: 'notifications',
|
|
78
|
+
token: 'your_token',
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
// Particleboard. The host comes from HEROKU_PARTICLEBOARD_URL, then
|
|
82
|
+
// particleboard.heroku.com. An explicit baseUrl takes precedence.
|
|
66
83
|
const particleboardClient = new HerokuApiClient({
|
|
67
84
|
service: 'particleboard',
|
|
68
85
|
token: 'your_token',
|
|
@@ -351,7 +368,7 @@ localStorage.debug = 'heroku-fetch:*';
|
|
|
351
368
|
```typescript
|
|
352
369
|
interface HerokuApiClientOptions {
|
|
353
370
|
/** Heroku service type */
|
|
354
|
-
service?: 'platform' | 'data' | 'particleboard' | 'custom';
|
|
371
|
+
service?: 'platform' | 'data' | 'metrics' | 'notifications' | 'particleboard' | 'repositories' | 'custom';
|
|
355
372
|
|
|
356
373
|
/** Static bearer token or function to retrieve token */
|
|
357
374
|
token?: string | (() => string | Promise<string>);
|
|
@@ -364,9 +381,6 @@ interface HerokuApiClientOptions {
|
|
|
364
381
|
/** Custom base URL (required for 'custom' service) */
|
|
365
382
|
baseUrl?: string;
|
|
366
383
|
|
|
367
|
-
/** Service region (e.g., 'eu', 'us') */
|
|
368
|
-
region?: string;
|
|
369
|
-
|
|
370
384
|
/** Request timeout in milliseconds (default: 30000) */
|
|
371
385
|
timeout?: number;
|
|
372
386
|
|
package/dist/client/index.d.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Heroku API Client
|
|
3
3
|
*
|
|
4
4
|
* Main client class for making HTTP requests to Heroku APIs.
|
|
5
|
-
* Supports multiple services (platform, data, particleboard), authentication,
|
|
5
|
+
* Supports multiple services (platform, data, metrics, notifications, particleboard, repositories), authentication,
|
|
6
6
|
* two-factor authentication, and comprehensive error handling.
|
|
7
7
|
*/
|
|
8
8
|
import type { HerokuApiClientOptions, RequestOptions } from '../types.js';
|
|
@@ -95,7 +95,8 @@ export declare class HerokuApiClient {
|
|
|
95
95
|
*
|
|
96
96
|
* Replaying a non-idempotent write this way is safe for Heroku's front-door
|
|
97
97
|
* auth, which rejects a 401 before the server executes the request. It is not
|
|
98
|
-
* universally safe: a
|
|
98
|
+
* universally safe: a host other than platform (`data`, `metrics`,
|
|
99
|
+
* `notifications`, `particleboard`, `repositories`, `custom`) that returns a
|
|
99
100
|
* downstream or proxied 401 *after* side effects have begun would see the
|
|
100
101
|
* write run twice. Opt such a request out with `reauthorize: false`.
|
|
101
102
|
*/
|
package/dist/client/index.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Heroku API Client
|
|
3
3
|
*
|
|
4
4
|
* Main client class for making HTTP requests to Heroku APIs.
|
|
5
|
-
* Supports multiple services (platform, data, particleboard), authentication,
|
|
5
|
+
* Supports multiple services (platform, data, metrics, notifications, particleboard, repositories), authentication,
|
|
6
6
|
* two-factor authentication, and comprehensive error handling.
|
|
7
7
|
*/
|
|
8
8
|
import { getDefaultFetch, getDefaultTokenProvider, getDefaultTwoFactorOptions, getUserAgentComment, } from '@heroku/heroku-fetch/client/environment-defaults.js';
|
|
@@ -53,14 +53,12 @@ export class HerokuApiClient {
|
|
|
53
53
|
}
|
|
54
54
|
// Determine base URL
|
|
55
55
|
const serviceConfig = SERVICE_CONFIGS[this.options.service];
|
|
56
|
-
let baseUrl = options.baseUrl || serviceConfig.baseUrl;
|
|
57
56
|
if (this.options.service === 'custom' && !options.baseUrl) {
|
|
58
57
|
throw new Error('baseUrl is required when service is "custom"');
|
|
59
58
|
}
|
|
60
|
-
//
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
}
|
|
59
|
+
// `||` keeps the service default unread when baseUrl is set: its getter
|
|
60
|
+
// validates the host env vars, and an unused one mustn't fail the client.
|
|
61
|
+
const baseUrl = options.baseUrl || serviceConfig.baseUrl;
|
|
64
62
|
debugAuth('Initializing client for service: %s, baseUrl: %s', this.options.service, baseUrl);
|
|
65
63
|
// Stash the ky options; the actual ky instance is built lazily so
|
|
66
64
|
// we can await getDefaultFetch() (Node loads undici dynamically for
|
|
@@ -166,7 +164,7 @@ export class HerokuApiClient {
|
|
|
166
164
|
}
|
|
167
165
|
// Only these are re-read on each request, so changing them takes effect.
|
|
168
166
|
// hooks, headers, the Accept default, the 2FA handler, and the
|
|
169
|
-
// service
|
|
167
|
+
// service base URL are baked into the cached ky instance at
|
|
170
168
|
// construction, so mutating them here would silently no-op — reject rather
|
|
171
169
|
// than lie about the change landing. `reauthorize` IS read per request (so a
|
|
172
170
|
// mutation would land), but is deliberately kept construction-only: it's an
|
|
@@ -295,7 +293,8 @@ export class HerokuApiClient {
|
|
|
295
293
|
*
|
|
296
294
|
* Replaying a non-idempotent write this way is safe for Heroku's front-door
|
|
297
295
|
* auth, which rejects a 401 before the server executes the request. It is not
|
|
298
|
-
* universally safe: a
|
|
296
|
+
* universally safe: a host other than platform (`data`, `metrics`,
|
|
297
|
+
* `notifications`, `particleboard`, `repositories`, `custom`) that returns a
|
|
299
298
|
* downstream or proxied 401 *after* side effects have begun would see the
|
|
300
299
|
* write run twice. Opt such a request out with `reauthorize: false`.
|
|
301
300
|
*/
|
|
@@ -1,2 +1,10 @@
|
|
|
1
1
|
import type { HerokuService, ServiceConfig } from '../types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Per-service defaults. Services whose host can be overridden by an environment
|
|
4
|
+
* variable use a `baseUrl` getter, so the variable is read when each client is
|
|
5
|
+
* built, not at import. `data` honors `HEROKU_DATA_HOST`, then
|
|
6
|
+
* `HEROKU_POSTGRESQL_HOST`, the variables the Heroku CLI has long used for the
|
|
7
|
+
* data API. `notifications` and `repositories` set no Accept default,
|
|
8
|
+
* matching what those hosts have always been sent.
|
|
9
|
+
*/
|
|
2
10
|
export declare const SERVICE_CONFIGS: Record<HerokuService, ServiceConfig>;
|
|
@@ -1,4 +1,46 @@
|
|
|
1
1
|
const HEROKU_V3_ACCEPT = 'application/vnd.heroku+json; version=3';
|
|
2
|
+
const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', '[::1]', 'localhost']);
|
|
3
|
+
/**
|
|
4
|
+
* The base URL from the first of `variables` that is set, else `fallback`.
|
|
5
|
+
* Values are trimmed, and blank ones are skipped. A bare hostname gets `https://`;
|
|
6
|
+
* a value with an `http://` or `https://` scheme, in any case, is used as-is.
|
|
7
|
+
* `process` and `process.env` are guarded for browser builds.
|
|
8
|
+
*
|
|
9
|
+
* Plain `http://` is allowed only for loopback hosts (local development), so the
|
|
10
|
+
* client's bearer token is never sent unencrypted to a remote host. Otherwise it
|
|
11
|
+
* throws, naming the variable but not echoing its value.
|
|
12
|
+
*/
|
|
13
|
+
function envBaseUrl(variables, fallback) {
|
|
14
|
+
const env = typeof process === 'undefined' ? undefined : process.env;
|
|
15
|
+
for (const variable of variables) {
|
|
16
|
+
const host = env?.[variable]?.trim();
|
|
17
|
+
if (!host)
|
|
18
|
+
continue;
|
|
19
|
+
if (!/^https?:\/\//i.test(host))
|
|
20
|
+
return `https://${host}`;
|
|
21
|
+
if (/^http:/i.test(host) && !isLoopback(host)) {
|
|
22
|
+
throw new Error(`${variable} must use https:// unless it points at localhost`);
|
|
23
|
+
}
|
|
24
|
+
return host;
|
|
25
|
+
}
|
|
26
|
+
return fallback;
|
|
27
|
+
}
|
|
28
|
+
function isLoopback(url) {
|
|
29
|
+
try {
|
|
30
|
+
return LOOPBACK_HOSTNAMES.has(new URL(url).hostname);
|
|
31
|
+
}
|
|
32
|
+
catch {
|
|
33
|
+
return false;
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Per-service defaults. Services whose host can be overridden by an environment
|
|
38
|
+
* variable use a `baseUrl` getter, so the variable is read when each client is
|
|
39
|
+
* built, not at import. `data` honors `HEROKU_DATA_HOST`, then
|
|
40
|
+
* `HEROKU_POSTGRESQL_HOST`, the variables the Heroku CLI has long used for the
|
|
41
|
+
* data API. `notifications` and `repositories` set no Accept default,
|
|
42
|
+
* matching what those hosts have always been sent.
|
|
43
|
+
*/
|
|
2
44
|
export const SERVICE_CONFIGS = {
|
|
3
45
|
custom: {
|
|
4
46
|
// Must be provided by user; no Accept default — the URL may be
|
|
@@ -7,15 +49,35 @@ export const SERVICE_CONFIGS = {
|
|
|
7
49
|
baseUrl: '',
|
|
8
50
|
},
|
|
9
51
|
data: {
|
|
10
|
-
baseUrl
|
|
52
|
+
get baseUrl() {
|
|
53
|
+
return envBaseUrl(['HEROKU_DATA_HOST', 'HEROKU_POSTGRESQL_HOST'], 'https://postgres-api.heroku.com');
|
|
54
|
+
},
|
|
11
55
|
defaultAccept: HEROKU_V3_ACCEPT,
|
|
12
56
|
},
|
|
57
|
+
metrics: {
|
|
58
|
+
get baseUrl() {
|
|
59
|
+
return envBaseUrl(['HEROKU_METRICS_HOST'], 'https://api.metrics.heroku.com');
|
|
60
|
+
},
|
|
61
|
+
defaultAccept: HEROKU_V3_ACCEPT,
|
|
62
|
+
},
|
|
63
|
+
notifications: {
|
|
64
|
+
get baseUrl() {
|
|
65
|
+
return envBaseUrl(['HEROKU_NOTIFICATIONS_HOST'], 'https://telex.heroku.com');
|
|
66
|
+
},
|
|
67
|
+
},
|
|
13
68
|
particleboard: {
|
|
14
|
-
baseUrl
|
|
69
|
+
get baseUrl() {
|
|
70
|
+
return envBaseUrl(['HEROKU_PARTICLEBOARD_URL'], 'https://particleboard.heroku.com');
|
|
71
|
+
},
|
|
15
72
|
defaultAccept: HEROKU_V3_ACCEPT,
|
|
16
73
|
},
|
|
17
74
|
platform: {
|
|
18
75
|
baseUrl: 'https://api.heroku.com',
|
|
19
76
|
defaultAccept: HEROKU_V3_ACCEPT,
|
|
20
77
|
},
|
|
78
|
+
repositories: {
|
|
79
|
+
get baseUrl() {
|
|
80
|
+
return envBaseUrl(['HEROKU_REPOSITORIES_HOST'], 'https://kolkrabbi.heroku.com');
|
|
81
|
+
},
|
|
82
|
+
},
|
|
21
83
|
};
|
package/dist/types.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export type HerokuService = 'custom' | 'data' | 'particleboard' | 'platform';
|
|
1
|
+
export type HerokuService = 'custom' | 'data' | 'metrics' | 'notifications' | 'particleboard' | 'platform' | 'repositories';
|
|
2
2
|
/**
|
|
3
3
|
* A `beforeRequest` hook: runs after the client's built-ins have prepared the
|
|
4
4
|
* `Request` and may inspect or mutate it, or return a replacement `Request`/
|
|
@@ -95,8 +95,6 @@ export interface ServiceConfig {
|
|
|
95
95
|
* type.
|
|
96
96
|
*/
|
|
97
97
|
defaultAccept?: string;
|
|
98
|
-
/** Default region (if applicable) */
|
|
99
|
-
region?: string;
|
|
100
98
|
}
|
|
101
99
|
/**
|
|
102
100
|
* Identifies the consumer in the `User-Agent` header: a product `name` and
|
|
@@ -182,9 +180,7 @@ export interface HerokuApiClientOptions {
|
|
|
182
180
|
reauthorize?: (context: {
|
|
183
181
|
signal?: AbortSignal;
|
|
184
182
|
}) => Promise<void> | void;
|
|
185
|
-
/**
|
|
186
|
-
region?: string;
|
|
187
|
-
/** Heroku service type (platform, data, particleboard, custom) */
|
|
183
|
+
/** Heroku service type (platform, data, metrics, notifications, particleboard, repositories, custom) */
|
|
188
184
|
service?: HerokuService;
|
|
189
185
|
/**
|
|
190
186
|
* Default `AbortSignal` applied to every request this client makes: when it
|