@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
- // Data API with EU region
59
- const euDataClient = new HerokuApiClient({
60
- service: 'data',
61
- region: 'eu',
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
- // Particleboard
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
 
@@ -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 `data`/`particleboard`/`custom` host that returns 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
  */
@@ -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
- // Apply region if specified (for services that support it)
61
- if (options.region && this.options.service === 'data') {
62
- baseUrl = `https://postgres-api-${options.region}.heroku.com`;
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/region base URL are baked into the cached ky instance at
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 `data`/`particleboard`/`custom` host that returns 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: 'https://postgres-api.heroku.com',
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: 'https://particleboard.heroku.com',
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
- /** Service region (e.g., 'eu', 'us') */
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@heroku/heroku-fetch",
3
- "version": "0.2.5",
3
+ "version": "0.3.0",
4
4
  "description": "A JavaScript/TypeScript API client for Heroku APIs",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",