@heroku/heroku-fetch 0.2.6 → 0.4.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,18 +55,39 @@ 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 https://api.data.heroku.com. A bare hostname
60
+ // gets https://. An explicit baseUrl takes precedence.
61
+ //
62
+ // Every environment-configured service host must use heroku.com, herokai.com,
63
+ // herokuspace.com, herokudev.com, or the loopback hosts localhost, 127.0.0.1
64
+ // and [::1]. Remote hosts require HTTPS; HTTP is allowed only for loopback.
65
+ // This applies to HEROKU_DATA_HOST, HEROKU_POSTGRESQL_HOST,
66
+ // HEROKU_METRICS_HOST, HEROKU_NOTIFICATIONS_HOST, HEROKU_PARTICLEBOARD_URL
67
+ // and HEROKU_REPOSITORIES_HOST.
68
+ // Configured URLs are reduced to their origin; user information, non-root
69
+ // paths, queries and fragments are rejected. Explicit baseUrl values remain
70
+ // the caller's responsibility. In particular, *.herokuapp.com is not trusted
71
+ // for environment-configured hosts; internal staging setups should use an
72
+ // approved Heroku-owned hostname instead.
73
+
74
+ // Metrics. The host comes from HEROKU_METRICS_HOST, then
75
+ // api.metrics.heroku.com. An explicit baseUrl takes precedence.
76
+ const metricsClient = new HerokuApiClient({
77
+ service: 'metrics',
62
78
  token: 'your_token',
63
79
  });
64
80
 
65
- // The data client's host comes from HEROKU_DATA_HOST, then
66
- // HEROKU_POSTGRESQL_HOST, then postgres-api.heroku.com. A bare hostname
67
- // gets https://. An explicit baseUrl or region takes precedence.
81
+ // Notifications (telex) and repositories (kolkrabbi). Their hosts come from
82
+ // HEROKU_NOTIFICATIONS_HOST / HEROKU_REPOSITORIES_HOST, then telex.heroku.com /
83
+ // kolkrabbi.heroku.com. Neither sends a default Accept header.
84
+ const notificationsClient = new HerokuApiClient({
85
+ service: 'notifications',
86
+ token: 'your_token',
87
+ });
68
88
 
69
- // Particleboard
89
+ // Particleboard. The host comes from HEROKU_PARTICLEBOARD_URL, then
90
+ // particleboard.heroku.com. An explicit baseUrl takes precedence.
70
91
  const particleboardClient = new HerokuApiClient({
71
92
  service: 'particleboard',
72
93
  token: 'your_token',
@@ -355,7 +376,7 @@ localStorage.debug = 'heroku-fetch:*';
355
376
  ```typescript
356
377
  interface HerokuApiClientOptions {
357
378
  /** Heroku service type */
358
- service?: 'platform' | 'data' | 'particleboard' | 'custom';
379
+ service?: 'platform' | 'data' | 'metrics' | 'notifications' | 'particleboard' | 'repositories' | 'custom';
359
380
 
360
381
  /** Static bearer token or function to retrieve token */
361
382
  token?: string | (() => string | Promise<string>);
@@ -368,9 +389,6 @@ interface HerokuApiClientOptions {
368
389
  /** Custom base URL (required for 'custom' service) */
369
390
  baseUrl?: string;
370
391
 
371
- /** Service region (e.g., 'eu', 'us') */
372
- region?: string;
373
-
374
392
  /** Request timeout in milliseconds (default: 30000) */
375
393
  timeout?: number;
376
394
 
@@ -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,17 +1,66 @@
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
+ const TRUSTED_HEROKU_DOMAINS = ['heroku.com', 'herokai.com', 'herokuspace.com', 'herokudev.com'];
2
4
  /**
3
- * The data API base URL: `HEROKU_DATA_HOST`, then `HEROKU_POSTGRESQL_HOST`,
4
- * then `https://postgres-api.heroku.com`. These are the variables the Heroku
5
- * CLI has long honored for the data API. A bare hostname gets `https://`; a
6
- * value with an `http://` or `https://` scheme, in any case, is used as-is. `process` is guarded for browser builds.
5
+ * The base URL from the first of `variables` that is set, else `fallback`.
6
+ * Values are trimmed, and blank ones are skipped. A bare hostname gets `https://`;
7
+ * a value with an `http://` or `https://` scheme is parsed as given.
8
+ * `process` and `process.env` are guarded for browser builds.
9
+ *
10
+ * Hostnames must be in an approved Heroku domain or loopback. Plain `http://` is
11
+ * allowed only for loopback hosts (local development), so the client's bearer
12
+ * token is never sent unencrypted to a remote host. Errors name the variable but
13
+ * never echo its value.
7
14
  */
8
- function dataBaseUrl() {
15
+ function envBaseUrl(variables, fallback) {
9
16
  const env = typeof process === 'undefined' ? undefined : process.env;
10
- const host = env?.HEROKU_DATA_HOST || env?.HEROKU_POSTGRESQL_HOST;
11
- if (!host)
12
- return 'https://postgres-api.heroku.com';
13
- return /^https?:\/\//i.test(host) ? host : `https://${host}`;
17
+ for (const variable of variables) {
18
+ const value = env?.[variable]?.trim();
19
+ if (!value)
20
+ continue;
21
+ return validatedEnvBaseUrl(variable, value);
22
+ }
23
+ return fallback;
14
24
  }
25
+ function validatedEnvBaseUrl(variable, value) {
26
+ const explicitScheme = /^[a-z][a-z\d+.-]*:\/\//i.test(value);
27
+ const candidate = explicitScheme ? value : `https://${value}`;
28
+ let url;
29
+ try {
30
+ url = new URL(candidate);
31
+ }
32
+ catch {
33
+ throw new Error(`${variable} must be a valid Heroku service URL`);
34
+ }
35
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') {
36
+ throw new Error(`${variable} must use http:// or https://`);
37
+ }
38
+ // URL.username/password omit an empty `@`, so also check the input for that
39
+ // delimiter before accepting the parsed URL.
40
+ if (url.username || url.password || candidate.includes('@')) {
41
+ throw new Error(`${variable} must not include user information`);
42
+ }
43
+ if (url.pathname !== '/' || url.search || url.hash || candidate.includes('?') || candidate.includes('#')) {
44
+ throw new Error(`${variable} must not include a path, query, or fragment`);
45
+ }
46
+ const loopback = LOOPBACK_HOSTNAMES.has(url.hostname);
47
+ if (url.protocol === 'http:' && !loopback) {
48
+ throw new Error(`${variable} must use https:// unless it points at localhost`);
49
+ }
50
+ const approvedDomain = TRUSTED_HEROKU_DOMAINS.some(domain => url.hostname === domain || url.hostname.endsWith(`.${domain}`));
51
+ if (!loopback && !approvedDomain) {
52
+ throw new Error(`${variable} must use a heroku.com, herokai.com, herokuspace.com, or herokudev.com host`);
53
+ }
54
+ return url.origin;
55
+ }
56
+ /**
57
+ * Per-service defaults. Services whose host can be overridden by an environment
58
+ * variable use a `baseUrl` getter, so the variable is read when each client is
59
+ * built, not at import. `data` honors `HEROKU_DATA_HOST`, then
60
+ * `HEROKU_POSTGRESQL_HOST`, the variables the Heroku CLI has long used for the
61
+ * data API. `notifications` and `repositories` set no Accept default,
62
+ * matching what those hosts have always been sent.
63
+ */
15
64
  export const SERVICE_CONFIGS = {
16
65
  custom: {
17
66
  // Must be provided by user; no Accept default — the URL may be
@@ -20,18 +69,35 @@ export const SERVICE_CONFIGS = {
20
69
  baseUrl: '',
21
70
  },
22
71
  data: {
23
- // A getter so the environment is read when each client is built, not at import.
24
72
  get baseUrl() {
25
- return dataBaseUrl();
73
+ return envBaseUrl(['HEROKU_DATA_HOST', 'HEROKU_POSTGRESQL_HOST'], 'https://api.data.heroku.com');
74
+ },
75
+ defaultAccept: HEROKU_V3_ACCEPT,
76
+ },
77
+ metrics: {
78
+ get baseUrl() {
79
+ return envBaseUrl(['HEROKU_METRICS_HOST'], 'https://api.metrics.heroku.com');
26
80
  },
27
81
  defaultAccept: HEROKU_V3_ACCEPT,
28
82
  },
83
+ notifications: {
84
+ get baseUrl() {
85
+ return envBaseUrl(['HEROKU_NOTIFICATIONS_HOST'], 'https://telex.heroku.com');
86
+ },
87
+ },
29
88
  particleboard: {
30
- baseUrl: 'https://particleboard.heroku.com',
89
+ get baseUrl() {
90
+ return envBaseUrl(['HEROKU_PARTICLEBOARD_URL'], 'https://particleboard.heroku.com');
91
+ },
31
92
  defaultAccept: HEROKU_V3_ACCEPT,
32
93
  },
33
94
  platform: {
34
95
  baseUrl: 'https://api.heroku.com',
35
96
  defaultAccept: HEROKU_V3_ACCEPT,
36
97
  },
98
+ repositories: {
99
+ get baseUrl() {
100
+ return envBaseUrl(['HEROKU_REPOSITORIES_HOST'], 'https://kolkrabbi.heroku.com');
101
+ },
102
+ },
37
103
  };
package/dist/redact.d.ts CHANGED
@@ -7,8 +7,8 @@
7
7
  /**
8
8
  * Scrub a value for debug logging. Handles `Error`, `Headers`, plain objects,
9
9
  * and primitives (passed through unchanged — a top-level string is not
10
- * pattern-scrubbed; `VALUE_PATTERNS` only apply to strings nested inside a
11
- * scrubbed object/Error). Fail-closed: any failure returns `'[unscrubbable]'`
10
+ * pattern-scrubbed; `CREDENTIAL_PATTERNS` only apply to strings nested inside
11
+ * a scrubbed object/Error). Fail-closed: any failure returns `'[unscrubbable]'`
12
12
  * rather than risking the raw value. `depth` is internal, for `cause`
13
13
  * recursion.
14
14
  */
package/dist/redact.js CHANGED
@@ -17,16 +17,6 @@ const EXTRA_FIELDS = [
17
17
  'otp',
18
18
  'sso',
19
19
  ];
20
- /**
21
- * Redact inline `Bearer`/`Basic` credentials in string leaf values reached
22
- * while scrubbing an object or Error (e.g. an error message). Bare UUIDs/JWTs
23
- * are intentionally not matched — they're indistinguishable from benign
24
- * resource IDs. Note these patterns don't apply to a top-level string passed
25
- * straight to `scrubForLog`.
26
- */
27
- const VALUE_PATTERNS = [
28
- /\b(?:Bearer|Basic)\s+[\w.~+/=-]+/gi,
29
- ];
30
20
  /** Cap on `error.cause` recursion depth; guards against cyclic chains. */
31
21
  const MAX_CAUSE_DEPTH = 8;
32
22
  let scrubberPromise;
@@ -34,13 +24,18 @@ let scrubberPromise;
34
24
  async function getScrubber() {
35
25
  if (!scrubberPromise) {
36
26
  scrubberPromise = (async () => {
37
- const [{ Scrubber }, { HEROKU_FIELDS }] = await Promise.all([
27
+ const [{ Scrubber }, { HEROKU_FIELDS }, { CREDENTIAL_PATTERNS }] = await Promise.all([
38
28
  import('@heroku/js-blanket/core/scrubber'),
39
29
  import('@heroku/js-blanket/core/presets'),
30
+ import('@heroku/js-blanket/core/patterns'),
40
31
  ]);
32
+ // CREDENTIAL_PATTERNS redact credentials in string values reached while
33
+ // scrubbing an object or Error, such as an error message: Heroku API
34
+ // tokens, Authorization values, Bearer/Basic credentials, URL passwords
35
+ // and PEM private keys. Each keeps its context (`Bearer [REDACTED]`).
41
36
  return new Scrubber({
42
37
  fields: [...HEROKU_FIELDS, ...EXTRA_FIELDS],
43
- patterns: [...VALUE_PATTERNS],
38
+ patterns: CREDENTIAL_PATTERNS,
44
39
  replacement: REPLACEMENT,
45
40
  });
46
41
  })();
@@ -122,8 +117,8 @@ async function scrubError(error, depth) {
122
117
  /**
123
118
  * Scrub a value for debug logging. Handles `Error`, `Headers`, plain objects,
124
119
  * and primitives (passed through unchanged — a top-level string is not
125
- * pattern-scrubbed; `VALUE_PATTERNS` only apply to strings nested inside a
126
- * scrubbed object/Error). Fail-closed: any failure returns `'[unscrubbable]'`
120
+ * pattern-scrubbed; `CREDENTIAL_PATTERNS` only apply to strings nested inside
121
+ * a scrubbed object/Error). Fail-closed: any failure returns `'[unscrubbable]'`
127
122
  * rather than risking the raw value. `depth` is internal, for `cause`
128
123
  * recursion.
129
124
  */
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.6",
3
+ "version": "0.4.0",
4
4
  "description": "A JavaScript/TypeScript API client for Heroku APIs",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -50,7 +50,7 @@
50
50
  },
51
51
  "homepage": "https://github.com/heroku/heroku-fetch#readme",
52
52
  "dependencies": {
53
- "@heroku/js-blanket": "^1.2.0",
53
+ "@heroku/js-blanket": "^1.4.0",
54
54
  "debug": "^4.3.4",
55
55
  "ky": "^2.2.0",
56
56
  "undici": "^8.11.2"