@heroku/heroku-fetch 0.1.1-beta.0

package/dist/client/index.js

@@ -0,0 +1,164 @@
+/**
+ * Heroku API Client
+ *
+ * Main client class for making HTTP requests to Heroku APIs.
+ * Supports multiple services (platform, data, particleboard), authentication,
+ * two-factor authentication, and comprehensive error handling.
+ */
+import { getDefaultDispatcher, getDefaultTokenProvider, getDefaultTwoFactorOptions } from '@heroku/heroku-fetch/client/environment-defaults.js';
+import ky from 'ky';
+import { debugAuth, debugRequest } from '../debug-loggers.js';
+import { createAfterResponseHook, createBeforeRequestHook } from './http-request-hooks.js';
+import { SERVICE_CONFIGS } from './service-configurations.js';
+export class HerokuApiClient {
+    constructor(options = {}) {
+        this.clientPromise = null;
+        this.twoFactorAttempted = { value: false };
+        this.options = {
+            service: options.service || 'platform',
+            timeout: options.timeout || 30000,
+            ...options,
+        };
+        // If no token provided, use default token provider
+        this.tokenProvider = options.token === undefined ? getDefaultTokenProvider() : options.token;
+        // If no twoFactor provided, use default 2FA handler
+        if (!options.twoFactor) {
+            this.options.twoFactor = getDefaultTwoFactorOptions();
+        }
+        // Determine base URL
+        const serviceConfig = SERVICE_CONFIGS[this.options.service];
+        let baseUrl = options.baseUrl || serviceConfig.baseUrl;
+        if (this.options.service === 'custom' && !options.baseUrl) {
+            throw new Error('baseUrl is required when service is "custom"');
+        }
+        // Apply region if specified (for services that support it)
+        if (options.region && this.options.service === 'data') {
+            baseUrl = `https://postgres-api-${options.region}.heroku.com`;
+        }
+        debugAuth('Initializing client for service: %s, baseUrl: %s', this.options.service, baseUrl);
+        // Stash the ky options; the actual ky instance is built lazily so
+        // we can await getDefaultDispatcher() (Node loads undici
+        // dynamically for env-var proxy support).
+        this.kyOptions = {
+            hooks: {
+                afterResponse: [
+                    createAfterResponseHook(this.options.twoFactor, this.twoFactorAttempted),
+                ],
+                beforeRequest: [
+                    createBeforeRequestHook(() => this.getToken(), serviceConfig.defaultAccept, options.headers, this.options.debug),
+                ],
+            },
+            prefix: baseUrl,
+            timeout: this.options.timeout,
+        };
+    }
+    /**
+     * Make a DELETE request
+     */
+    async delete(path, options) {
+        debugRequest('DELETE %s', path);
+        return this.request(path, { ...options, method: 'DELETE' });
+    }
+    /**
+     * Make a GET request
+     */
+    async get(path, options) {
+        debugRequest('GET %s', path);
+        return this.request(path, { ...options, method: 'GET' });
+    }
+    /**
+     * Make a PATCH request
+     */
+    async patch(path, body, options) {
+        debugRequest('PATCH %s', path);
+        return this.request(path, { ...options, body, method: 'PATCH' });
+    }
+    /**
+     * Make a POST request
+     */
+    async post(path, body, options) {
+        debugRequest('POST %s', path);
+        return this.request(path, { ...options, body, method: 'POST' });
+    }
+    /**
+     * Make a PUT request
+     */
+    async put(path, body, options) {
+        debugRequest('PUT %s', path);
+        return this.request(path, { ...options, body, method: 'PUT' });
+    }
+    /**
+     * Set or update a client option
+     */
+    setOption(key, value) {
+        if (key === 'token') {
+            this.tokenProvider = value;
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            this.options[key] = value;
+        }
+    }
+    /**
+     * Create a streaming request (returns the Response object for stream access)
+     */
+    async stream(path, options) {
+        debugRequest('STREAM %s', path);
+        const kyOptions = {
+            headers: options?.headers,
+            method: 'GET',
+            searchParams: options?.searchParams,
+            signal: options?.signal,
+            timeout: options?.timeout || this.options.timeout,
+        };
+        const client = await this.getClient();
+        return client(path, kyOptions);
+    }
+    /**
+     * Lazily construct ky with an env-aware undici dispatcher (Node)
+     * or no dispatcher (browser). Cached after the first call.
+     */
+    async getClient() {
+        if (!this.clientPromise) {
+            this.clientPromise = (async () => {
+                const dispatcher = await getDefaultDispatcher();
+                // ky's type definitions don't include `dispatcher`; it's
+                // passed through to fetch as undici expects it.
+                const opts = dispatcher
+                    ? { ...this.kyOptions, dispatcher }
+                    : this.kyOptions;
+                return ky.create(opts);
+            })();
+        }
+        return this.clientPromise;
+    }
+    /**
+     * Get the authorization token
+     */
+    async getToken() {
+        if (!this.tokenProvider) {
+            return undefined;
+        }
+        if (typeof this.tokenProvider === 'string') {
+            return this.tokenProvider;
+        }
+        return this.tokenProvider();
+    }
+    /**
+     * Make a request with full control over options
+     */
+    async request(path, options) {
+        const kyOptions = {
+            headers: options?.headers,
+            method: options?.method || 'GET',
+            searchParams: options?.searchParams,
+            signal: options?.signal,
+            timeout: options?.timeout || this.options.timeout,
+        };
+        if (options?.body !== undefined) {
+            kyOptions.json = options.body;
+        }
+        const client = await this.getClient();
+        return client(path, kyOptions);
+    }
+}

package/dist/client/node-environment-defaults.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Default providers for Node.js environments
+ * These use file system (netrc) and CLI utilities
+ */
+import type { TokenProvider, TwoFactorOptions } from '../types.js';
+/**
+ * Get default token provider for Node.js (uses netrc/env vars)
+ */
+export declare function getDefaultTokenProvider(): TokenProvider;
+/**
+ * Get default 2FA handler for Node.js (uses CLI prompts)
+ */
+export declare function getDefaultTwoFactorOptions(): TwoFactorOptions;
+/**
+ * Get an undici Dispatcher that routes Node's fetch through an
+ * `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`-aware proxy agent.
+ *
+ * Returns `undefined` when no proxy env var is set, so we don't
+ * install a custom dispatcher that bypasses Node's global agent
+ * (and the `http`/`https` interceptors that test libraries
+ * intercept).
+ *
+ * Returns `undefined` when undici isn't loadable (e.g. on a non-Node
+ * runtime like Bun that exposes `process.versions.node` but doesn't
+ * ship undici); callers should skip the option in that case so ky
+ * falls back to native fetch.
+ *
+ * ky forwards the `dispatcher` option through to the underlying
+ * fetch — see https://github.com/sindresorhus/ky#proxy-support-nodejs.
+ */
+export declare function getDefaultDispatcher(): Promise<undefined | unknown>;

package/dist/client/node-environment-defaults.js

@@ -0,0 +1,68 @@
+/**
+ * Default providers for Node.js environments
+ * These use file system (netrc) and CLI utilities
+ */
+import { debugRequest } from '../debug-loggers.js';
+/**
+ * Get default token provider for Node.js (uses netrc/env vars)
+ */
+export function getDefaultTokenProvider() {
+    return async () => {
+        const { getAuthToken } = await import('../auth/auth.js');
+        const token = getAuthToken();
+        if (!token) {
+            throw new Error('No authentication token found. Please set HEROKU_API_KEY or run: heroku login');
+        }
+        return token;
+    };
+}
+/**
+ * Get default 2FA handler for Node.js (uses CLI prompts)
+ */
+export function getDefaultTwoFactorOptions() {
+    return {
+        async onChallenge() {
+            const { cliTwoFactorPrompt } = await import('../cli/cli-two-factor-prompt.js');
+            return cliTwoFactorPrompt();
+        },
+    };
+}
+/**
+ * Get an undici Dispatcher that routes Node's fetch through an
+ * `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`-aware proxy agent.
+ *
+ * Returns `undefined` when no proxy env var is set, so we don't
+ * install a custom dispatcher that bypasses Node's global agent
+ * (and the `http`/`https` interceptors that test libraries
+ * intercept).
+ *
+ * Returns `undefined` when undici isn't loadable (e.g. on a non-Node
+ * runtime like Bun that exposes `process.versions.node` but doesn't
+ * ship undici); callers should skip the option in that case so ky
+ * falls back to native fetch.
+ *
+ * ky forwards the `dispatcher` option through to the underlying
+ * fetch — see https://github.com/sindresorhus/ky#proxy-support-nodejs.
+ */
+export async function getDefaultDispatcher() {
+    if (!hasProxyEnv()) {
+        return undefined;
+    }
+    try {
+        // Dynamic import keeps undici out of browser bundles (the
+        // package.json `browser` condition resolves this whole module
+        // away in browser builds).
+        const { EnvHttpProxyAgent } = await import('undici');
+        return new EnvHttpProxyAgent();
+    }
+    catch (error) {
+        debugRequest('undici not available; skipping dispatcher (%o)', error);
+        return undefined;
+    }
+}
+function hasProxyEnv() {
+    return Boolean(process.env.HTTP_PROXY
+        || process.env.http_proxy
+        || process.env.HTTPS_PROXY
+        || process.env.https_proxy);
+}

package/dist/client/service-configurations.d.ts

@@ -0,0 +1,2 @@
+import type { HerokuService, ServiceConfig } from '../types.js';
+export declare const SERVICE_CONFIGS: Record<HerokuService, ServiceConfig>;

package/dist/client/service-configurations.js

@@ -0,0 +1,21 @@
+const HEROKU_V3_ACCEPT = 'application/vnd.heroku+json; version=3';
+export const SERVICE_CONFIGS = {
+    custom: {
+        // Must be provided by user; no Accept default — the URL may be
+        // a third-party host (logplex, busl, GitHub) that wouldn't
+        // recognize the Heroku vendor MIME type.
+        baseUrl: '',
+    },
+    data: {
+        baseUrl: 'https://postgres-api.heroku.com',
+        defaultAccept: HEROKU_V3_ACCEPT,
+    },
+    particleboard: {
+        baseUrl: 'https://particleboard.heroku.com',
+        defaultAccept: HEROKU_V3_ACCEPT,
+    },
+    platform: {
+        baseUrl: 'https://api.heroku.com',
+        defaultAccept: HEROKU_V3_ACCEPT,
+    },
+};

package/dist/client/two-factor-authentication-handler.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Two-Factor Authentication Handler Module
+ *
+ * Handles detection and processing of 2FA challenges from the API.
+ */
+import type { TwoFactorOptions } from '../types.js';
+/**
+ * Check if a 403 response is a 2FA error by checking the error id
+ */
+export declare function is2FAError(response: Response): Promise<boolean>;
+/**
+ * Handle a 2FA challenge by prompting for a code and retrying the request
+ */
+export declare function handle2FAChallenge(request: Request, twoFactorOptions: TwoFactorOptions, twoFactorAttemptedRef: {
+    value: boolean;
+}): Promise<Response>;

package/dist/client/two-factor-authentication-handler.js

@@ -0,0 +1,53 @@
+/**
+ * Two-Factor Authentication Handler Module
+ *
+ * Handles detection and processing of 2FA challenges from the API.
+ */
+import ky from 'ky';
+import { debugAuth, debugError } from '../debug-loggers.js';
+/**
+ * Check if a 403 response is a 2FA error by checking the error id
+ */
+export async function is2FAError(response) {
+    try {
+        const clonedResponse = response.clone();
+        const contentType = clonedResponse.headers.get('content-type');
+        if (contentType?.includes('application/json')) {
+            const errorBody = await clonedResponse.json();
+            return errorBody.id === 'two_factor';
+        }
+    }
+    catch {
+        // Failed to parse, assume not a 2FA error
+    }
+    return false;
+}
+/**
+ * Handle a 2FA challenge by prompting for a code and retrying the request
+ */
+export async function handle2FAChallenge(request, twoFactorOptions, twoFactorAttemptedRef) {
+    twoFactorAttemptedRef.value = true;
+    debugAuth('2FA challenge detected, invoking callback');
+    try {
+        const twoFactorCode = await twoFactorOptions.onChallenge();
+        debugAuth('2FA code received, retrying request');
+        // Retry the request with 2FA code
+        const headers = {};
+        // eslint-disable-next-line unicorn/no-array-for-each
+        request.headers.forEach((value, key) => {
+            headers[key] = value;
+        });
+        headers['Heroku-Two-Factor-Code'] = twoFactorCode;
+        const retryRequest = new Request(request, {
+            headers,
+        });
+        const retryResponse = await ky(retryRequest);
+        twoFactorAttemptedRef.value = false;
+        return retryResponse;
+    }
+    catch (error) {
+        twoFactorAttemptedRef.value = false;
+        debugError('2FA retry failed: %O', error);
+        throw error;
+    }
+}

package/dist/debug-loggers.d.ts

@@ -0,0 +1,6 @@
+import debug from 'debug';
+export declare const debugRequest: debug.Debugger;
+export declare const debugResponse: debug.Debugger;
+export declare const debugAuth: debug.Debugger;
+export declare const debugError: debug.Debugger;
+export declare const debugCliLogin: debug.Debugger;

package/dist/debug-loggers.js

@@ -0,0 +1,6 @@
+import debug from 'debug';
+export const debugRequest = debug('heroku:fetch:request');
+export const debugResponse = debug('heroku:fetch:response');
+export const debugAuth = debug('heroku:fetch:auth');
+export const debugError = debug('heroku:fetch:error');
+export const debugCliLogin = debug('heroku:fetch:cli:login');

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+import type { HerokuErrorResponse } from './types.js';
+export declare class HerokuApiError extends Error {
+    errors?: Array<{
+        id: string;
+        message: string;
+    }>;
+    id?: string;
+    resource?: string;
+    response?: Response;
+    statusCode: number;
+    constructor(message: string, statusCode: number, response?: Response, errorBody?: HerokuErrorResponse);
+}
+export declare class TwoFactorRequiredError extends HerokuApiError {
+    constructor(response: Response, errorBody?: HerokuErrorResponse);
+}
+export declare class AuthenticationError extends HerokuApiError {
+    constructor(response: Response, errorBody?: HerokuErrorResponse);
+}
+export declare class NotFoundError extends HerokuApiError {
+    constructor(response: Response, errorBody?: HerokuErrorResponse);
+}
+export declare class RateLimitError extends HerokuApiError {
+    retryAfter?: number;
+    constructor(response: Response, errorBody?: HerokuErrorResponse);
+}

package/dist/errors.js

@@ -0,0 +1,57 @@
+export class HerokuApiError extends Error {
+    constructor(message, statusCode, response, errorBody) {
+        super(message);
+        this.name = 'HerokuApiError';
+        this.statusCode = statusCode;
+        this.response = response;
+        if (errorBody) {
+            this.id = errorBody.id;
+            this.errors = errorBody.errors;
+            this.resource = errorBody.resource;
+        }
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, HerokuApiError);
+        }
+    }
+}
+export class TwoFactorRequiredError extends HerokuApiError {
+    constructor(response, errorBody) {
+        super('Two-factor authentication required', response.status, response, errorBody);
+        this.name = 'TwoFactorRequiredError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, TwoFactorRequiredError);
+        }
+    }
+}
+export class AuthenticationError extends HerokuApiError {
+    constructor(response, errorBody) {
+        super('Authentication failed', 401, response, errorBody);
+        this.name = 'AuthenticationError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, AuthenticationError);
+        }
+    }
+}
+export class NotFoundError extends HerokuApiError {
+    constructor(response, errorBody) {
+        super('Resource not found', 404, response, errorBody);
+        this.name = 'NotFoundError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, NotFoundError);
+        }
+    }
+}
+export class RateLimitError extends HerokuApiError {
+    constructor(response, errorBody) {
+        super('Rate limit exceeded', 429, response, errorBody);
+        this.name = 'RateLimitError';
+        const retryAfter = response.headers.get('Retry-After');
+        if (retryAfter) {
+            this.retryAfter = Number.parseInt(retryAfter, 10);
+        }
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, RateLimitError);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { getApiHost, getApiUrl, getAuthToken, getAuthTokenProvider, } from './auth/auth.js';
+export { Login } from './cli/cli-login.js';
+export { cliTwoFactorPrompt, createCliTwoFactorPrompt, } from './cli/cli-two-factor-prompt.js';
+export { HerokuApiClient } from './client/index.js';
+export { AuthenticationError, HerokuApiError, NotFoundError, RateLimitError, TwoFactorRequiredError, } from './errors.js';
+export type { HerokuApiClientOptions, HerokuError, HerokuErrorResponse, HerokuService, RequestOptions, ServiceConfig, TokenProvider, TwoFactorOptions, } from './types.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { getApiHost, getApiUrl, getAuthToken, getAuthTokenProvider, } from './auth/auth.js';
+export { Login } from './cli/cli-login.js';
+export { cliTwoFactorPrompt, createCliTwoFactorPrompt, } from './cli/cli-two-factor-prompt.js';
+export { HerokuApiClient } from './client/index.js';
+export { AuthenticationError, HerokuApiError, NotFoundError, RateLimitError, TwoFactorRequiredError, } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+export type HerokuService = 'custom' | 'data' | 'particleboard' | 'platform';
+export type TokenProvider = (() => Promise<string> | string) | string;
+export interface TwoFactorOptions {
+    /** Callback function to prompt for 2FA code */
+    onChallenge: () => Promise<string> | string;
+}
+export interface ServiceConfig {
+    /** Base URL for the service */
+    baseUrl: string;
+    /**
+     * Default Accept header to apply to outgoing requests when the
+     * caller hasn't set one. Omit for services that should not inject
+     * any Accept default — e.g. `custom`, where the URL may be a
+     * third-party host that wouldn't recognize the Heroku vendor MIME
+     * type.
+     */
+    defaultAccept?: string;
+    /** Default region (if applicable) */
+    region?: string;
+}
+export interface HerokuApiClientOptions {
+    /** Custom base URL (for 'custom' service type) */
+    baseUrl?: string;
+    /** Enable debugging */
+    debug?: boolean;
+    /** Additional custom headers */
+    headers?: Record<string, string>;
+    /** Service region (e.g., 'eu', 'us') */
+    region?: string;
+    /** Heroku service type (platform, data, particleboard, custom) */
+    service?: HerokuService;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Static bearer token or function to retrieve token */
+    token?: TokenProvider;
+    /** Two-factor authentication configuration */
+    twoFactor?: TwoFactorOptions;
+}
+export interface RequestOptions {
+    /** Additional headers for this request */
+    headers?: Record<string, string>;
+    /** Query parameters */
+    searchParams?: Record<string, boolean | number | string>;
+    /** Aborts the in-flight request when the signal fires. */
+    signal?: AbortSignal;
+    /** Enable streaming response */
+    stream?: boolean;
+    /** Request timeout override */
+    timeout?: number;
+}
+export interface HerokuError {
+    id: string;
+    message: string;
+}
+export interface HerokuErrorResponse {
+    errors?: HerokuError[];
+    id: string;
+    message?: string;
+    /**
+     * The kind of resource that was missing or invalid (e.g. `add_on`,
+     * `app`). Returned by the platform on certain 404/422 responses;
+     * absent on others.
+     */
+    resource?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@heroku/heroku-fetch",
+  "version": "0.1.1-beta.0",
+  "description": "A JavaScript/TypeScript API client for Heroku APIs",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/browser.d.ts",
+        "default": "./dist/browser.js"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client/environment-defaults.js": {
+      "browser": "./dist/client/browser-environment-defaults.js",
+      "default": "./dist/client/node-environment-defaults.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:report": "vitest run --coverage --coverage.reporter=html --coverage.reporter=text",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "heroku",
+    "api",
+    "client",
+    "fetch",
+    "typescript"
+  ],
+  "author": "Heroku",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "debug": "^4.3.4",
+    "ky": "^2.0.2",
+    "undici": "^6.25.0"
+  },
+  "optionalDependencies": {
+    "@heroku/heroku-cli-util": "^10.8.0",
+    "netrc-parser": "^3.1.6",
+    "open": "^11.0.0"
+  },
+  "devDependencies": {
+    "@heroku-cli/test-utils": "^0.2.0",
+    "@oclif/core": "^4.10.5",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^20.11.19",
+    "@vitest/coverage-v8": "^4.1.6",
+    "eslint": "^9.39.4",
+    "eslint-config-oclif": "^6.0.152",
+    "tsx": "^4.7.1",
+    "typescript": "^5.3.3",
+    "vitest": "^4.1.6"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}