@heroku/heroku-fetch 0.1.1-beta.0

package/dist/cli/login/netrc-utils.js

@@ -0,0 +1,85 @@
+/**
+ * Netrc file management utilities
+ */
+import { Netrc } from 'netrc-parser';
+import { debugCliLogin } from '../../debug-loggers.js';
+// Defer netrc instantiation to avoid eager file operations
+let _netrc;
+export function getNetrc() {
+    if (!_netrc) {
+        _netrc = new Netrc();
+    }
+    return _netrc;
+}
+/**
+ * Save authentication token to netrc file
+ */
+export async function saveToken(entry, apiHost, httpGitHost) {
+    debugCliLogin('Saving credentials to netrc for hosts: %s, %s', apiHost, httpGitHost);
+    const netrc = getNetrc();
+    await netrc.load();
+    const hosts = [apiHost, httpGitHost];
+    for (const host of hosts) {
+        if (!netrc.machines[host])
+            netrc.machines[host] = {};
+        netrc.machines[host].login = entry.login;
+        netrc.machines[host].password = entry.password;
+        delete netrc.machines[host].method;
+        delete netrc.machines[host].org;
+        debugCliLogin('Set credentials for host: %s (login: %s)', host, entry.login);
+    }
+    if (netrc.machines._tokens) {
+        // eslint-disable-next-line unicorn/no-array-for-each
+        netrc.machines._tokens.forEach((token) => {
+            if (hosts.includes(token.host)) {
+                token.internalWhitespace = '\n  ';
+            }
+        });
+    }
+    await netrc.save();
+    debugCliLogin('Netrc file saved successfully');
+}
+/**
+ * Clear authentication tokens from netrc file
+ */
+export async function clearTokens(apiHost, httpGitHost) {
+    debugCliLogin('Clearing credentials from netrc for hosts: %s, %s', apiHost, httpGitHost);
+    const netrc = getNetrc();
+    await netrc.load();
+    delete netrc.machines[apiHost];
+    delete netrc.machines[httpGitHost];
+    await netrc.save();
+    debugCliLogin('Credentials cleared from netrc successfully');
+}
+/**
+ * Get stored token from netrc file
+ */
+export async function getStoredToken(apiHost) {
+    debugCliLogin('Reading stored token from netrc for host: %s', apiHost);
+    const netrc = getNetrc();
+    await netrc.load();
+    const entry = netrc.machines[apiHost];
+    if (entry?.password) {
+        debugCliLogin('Token found in netrc for host: %s', apiHost);
+    }
+    else {
+        debugCliLogin('No token found in netrc for host: %s', apiHost);
+    }
+    return entry?.password;
+}
+/**
+ * Get stored login from netrc file
+ */
+export async function getStoredLogin(apiHost) {
+    debugCliLogin('Reading stored login from netrc for host: %s', apiHost);
+    const netrc = getNetrc();
+    await netrc.load();
+    const entry = netrc.machines[apiHost];
+    if (entry?.login) {
+        debugCliLogin('Login found in netrc for host: %s (login: %s)', apiHost, entry.login);
+    }
+    else {
+        debugCliLogin('No login found in netrc for host: %s', apiHost);
+    }
+    return entry?.login;
+}

package/dist/cli/login/oauth.d.ts

@@ -0,0 +1,20 @@
+/**
+ * OAuth token operations
+ */
+import type { HerokuApiClient } from '../../client/index.js';
+import type { NetrcEntry } from './types.js';
+/**
+ * Create an OAuth token via the Heroku API
+ */
+export declare function createOAuthToken(apiUrl: string, username: string, password: string, opts?: {
+    expiresIn?: number;
+    secondFactor?: string;
+}): Promise<NetrcEntry>;
+/**
+ * Get the default OAuth token for the current user
+ */
+export declare function getDefaultToken(client: HerokuApiClient): Promise<string | undefined>;
+/**
+ * Delete OAuth session and authorizations for the given token
+ */
+export declare function deleteOAuthTokens(client: HerokuApiClient, token: string): Promise<void>;

package/dist/cli/login/oauth.js

@@ -0,0 +1,142 @@
+/**
+ * OAuth token operations
+ */
+import os from 'node:os';
+import { debugCliLogin } from '../../debug-loggers.js';
+import { THIRTY_DAYS } from './types.js';
+const hostname = os.hostname();
+/**
+ * Create a basic auth header value
+ */
+function basicAuth(username, password) {
+    const auth = Buffer.from([username, password].join(':')).toString('base64');
+    return `Basic ${auth}`;
+}
+/**
+ * Create an OAuth token via the Heroku API
+ */
+export async function createOAuthToken(apiUrl, username, password, opts = {}) {
+    debugCliLogin('Creating OAuth authorization for user: %s', username);
+    debugCliLogin('Expires in: %d seconds%s', opts.expiresIn || THIRTY_DAYS, opts.secondFactor ? ', with 2FA' : '');
+    const requestHeaders = {
+        Accept: 'application/vnd.heroku+json; version=3',
+        Authorization: basicAuth(username, password),
+        'Content-Type': 'application/json',
+    };
+    if (opts.secondFactor) {
+        requestHeaders['Heroku-Two-Factor-Code'] = opts.secondFactor;
+    }
+    const response = await fetch(`${apiUrl}/oauth/authorizations`, {
+        body: JSON.stringify({
+            description: `Heroku CLI login from ${hostname}`,
+            expires_in: opts.expiresIn || THIRTY_DAYS,
+            scope: ['global'],
+        }),
+        headers: requestHeaders,
+        method: 'POST',
+    });
+    if (!response.ok) {
+        const errorBody = await response.json();
+        debugCliLogin('OAuth authorization creation failed: %d %s (error id: %s)', response.status, response.statusText, errorBody.id);
+        const error = new Error(errorBody.message || response.statusText);
+        error.statusCode = response.status;
+        error.body = errorBody;
+        throw error;
+    }
+    const auth = (await response.json());
+    debugCliLogin('OAuth authorization created successfully (id: %s)', auth.id);
+    return {
+        login: auth.user.email,
+        password: auth.access_token.token,
+    };
+}
+/**
+ * Get the default OAuth token for the current user
+ */
+export async function getDefaultToken(client) {
+    try {
+        debugCliLogin('Fetching default OAuth authorization');
+        const response = await client.get('/oauth/authorizations/~');
+        const authorization = (await response.json());
+        debugCliLogin('Default authorization found: %s', authorization.id);
+        return authorization.access_token?.token;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            const errBody = error.body;
+            if (errBody?.id === 'not_found'
+                && errBody?.resource === 'authorization') {
+                debugCliLogin('Default authorization not found');
+                return;
+            }
+            if (errBody?.id === 'unauthorized') {
+                debugCliLogin('Unauthorized to fetch default authorization');
+                return;
+            }
+        }
+        debugCliLogin('Error fetching default authorization: %O', error);
+        throw error;
+    }
+}
+/**
+ * Delete OAuth session and authorizations for the given token
+ */
+export async function deleteOAuthTokens(client, token) {
+    debugCliLogin('Deleting OAuth tokens and sessions');
+    // Delete the OAuth session (for SSO logins)
+    const sessionDeletion = client
+        .delete('/oauth/sessions/~')
+        .then(() => {
+        debugCliLogin('OAuth session deleted successfully');
+    })
+        .catch(error => {
+        if (error instanceof Error) {
+            const errBody = error.body;
+            if (errBody?.id === 'not_found'
+                && errBody?.resource === 'session') {
+                debugCliLogin('OAuth session not found (expected for non-SSO logins)');
+                return;
+            }
+            if (errBody?.id === 'unauthorized') {
+                debugCliLogin('Unauthorized to delete OAuth session');
+                return;
+            }
+        }
+        debugCliLogin('Error deleting OAuth session: %O', error);
+        throw error;
+    });
+    // Delete OAuth authorizations matching this token
+    const authorizationsDeletion = client
+        .get('/oauth/authorizations')
+        .then(async (response) => {
+        const authorizations = (await response.json());
+        debugCliLogin('Found %d OAuth authorizations', authorizations.length);
+        // Don't delete the default token
+        const defaultToken = await getDefaultToken(client);
+        if (defaultToken === token) {
+            debugCliLogin('Token matches default authorization, skipping deletion');
+            return;
+        }
+        const matchingAuths = authorizations.filter(a => a.access_token && a.access_token.token === token);
+        debugCliLogin('Found %d authorizations matching token', matchingAuths.length);
+        if (matchingAuths.length > 0) {
+            return Promise.all(matchingAuths.map(a => {
+                debugCliLogin('Deleting OAuth authorization: %s', a.id);
+                return client.delete(`/oauth/authorizations/${a.id}`);
+            }));
+        }
+    })
+        .catch(error => {
+        if (error instanceof Error) {
+            const errBody = error.body;
+            if (errBody?.id === 'unauthorized') {
+                debugCliLogin('Unauthorized to list/delete OAuth authorizations');
+                return [];
+            }
+        }
+        debugCliLogin('Error deleting OAuth authorizations: %O', error);
+        throw error;
+    });
+    await Promise.all([sessionDeletion, authorizationsDeletion]);
+    debugCliLogin('OAuth token deletion completed');
+}

package/dist/cli/login/sso-login.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SSO (Single Sign-On) login flow
+ */
+import type { LoginConfig, NetrcEntry } from './types.js';
+/**
+ * Perform SSO login
+ */
+export declare function ssoLogin(config: LoginConfig): Promise<NetrcEntry>;

package/dist/cli/login/sso-login.js

@@ -0,0 +1,41 @@
+/**
+ * SSO (Single Sign-On) login flow
+ */
+import { prompt } from '@heroku/heroku-cli-util/hux';
+import { debugCliLogin } from '../../debug-loggers.js';
+import { headers } from './types.js';
+/**
+ * Perform SSO login
+ */
+export async function ssoLogin(config) {
+    const open = (await import('open')).default;
+    let url = process.env.SSO_URL;
+    let org = process.env.HEROKU_ORGANIZATION;
+    if (!url) {
+        const orgName = await prompt('Organization name', {
+            default: org,
+            type: 'input',
+        });
+        org = orgName;
+        url = `https://sso.heroku.com/saml/${encodeURIComponent(org)}/init?cli=true`;
+    }
+    debugCliLogin(`opening browser to ${url}`);
+    console.error(`Opening browser to:\n${url}\n`);
+    console.error('\u001B[90mIf the browser fails to open or you\'re authenticating on a remote\nmachine, please manually open the URL above in your browser.\u001B[0m\n');
+    await open(url, { wait: false });
+    const password = await prompt('Access token', {
+        type: 'password',
+    });
+    console.error('Validating token...');
+    const response = await fetch(`${config.apiUrl}/account`, {
+        headers: headers(password),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to validate token: ${response.statusText}`);
+    }
+    const account = (await response.json());
+    return {
+        login: account.email,
+        password,
+    };
+}

package/dist/cli/login/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared types and interfaces for login functionality
+ */
+export interface NetrcEntry {
+    login: string;
+    password: string;
+}
+export interface OAuthAuthorization {
+    access_token?: {
+        token: string;
+    };
+    id: string;
+    user?: {
+        email: string;
+    };
+}
+export interface Account {
+    email: string;
+    id: string;
+}
+export interface LoginOptions {
+    /** Browser to use for browser-based login */
+    browser?: string;
+    /** Token expiration time in seconds */
+    expiresIn?: number;
+    /** Login method to use */
+    method?: 'browser' | 'interactive' | 'sso';
+}
+export interface LoginConfig {
+    apiHost: string;
+    apiUrl: string;
+    httpGitHost: string;
+    loginHost: string;
+}
+/** Helper to create HTTP headers with bearer token */
+export declare const headers: (token: string) => {
+    Accept: string;
+    Authorization: string;
+};
+/** Constants */
+export declare const THIRTY_DAYS: number;
+export declare const LOGIN_TIMEOUT: number;

package/dist/cli/login/types.js

@@ -0,0 +1,11 @@
+/**
+ * Shared types and interfaces for login functionality
+ */
+/** Helper to create HTTP headers with bearer token */
+export const headers = (token) => ({
+    Accept: 'application/vnd.heroku+json; version=3',
+    Authorization: `Bearer ${token}`,
+});
+/** Constants */
+export const THIRTY_DAYS = 60 * 60 * 24 * 30;
+export const LOGIN_TIMEOUT = 1000 * 60 * 10; // 10 minutes

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

@@ -0,0 +1,22 @@
+/**
+ * Default providers for browser environments
+ * These are minimal since browsers don't have file system or CLI access
+ */
+import type { TokenProvider, TwoFactorOptions } from '../types.js';
+/**
+ * Get default token provider for browsers (none - must be explicitly provided)
+ */
+export declare function getDefaultTokenProvider(): TokenProvider | undefined;
+/**
+ * Get default 2FA handler for browsers (none - must be explicitly provided)
+ */
+export declare function getDefaultTwoFactorOptions(): TwoFactorOptions | undefined;
+/**
+ * Get a default dispatcher for the browser.
+ *
+ * Always `undefined`. Browsers route through their own proxy stack
+ * (OS / browser settings), and the `dispatcher` option is undici-
+ * specific anyway — passing it would be ignored or could surface as
+ * a TypeError in some bundlers.
+ */
+export declare function getDefaultDispatcher(): Promise<undefined>;

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

@@ -0,0 +1,27 @@
+/**
+ * Default providers for browser environments
+ * These are minimal since browsers don't have file system or CLI access
+ */
+/**
+ * Get default token provider for browsers (none - must be explicitly provided)
+ */
+export function getDefaultTokenProvider() {
+    return undefined;
+}
+/**
+ * Get default 2FA handler for browsers (none - must be explicitly provided)
+ */
+export function getDefaultTwoFactorOptions() {
+    return undefined;
+}
+/**
+ * Get a default dispatcher for the browser.
+ *
+ * Always `undefined`. Browsers route through their own proxy stack
+ * (OS / browser settings), and the `dispatcher` option is undici-
+ * specific anyway — passing it would be ignored or could surface as
+ * a TypeError in some bundlers.
+ */
+export async function getDefaultDispatcher() {
+    return undefined;
+}

package/dist/client/http-error-handler.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Error Handler Module
+ *
+ * Handles parsing HTTP error responses and converting them to typed exceptions.
+ */
+/**
+ * Parse and handle an error response from the API
+ * Throws appropriate typed error based on status code
+ */
+export declare function handleErrorResponse(response: Response): Promise<never>;

package/dist/client/http-error-handler.js

@@ -0,0 +1,44 @@
+/**
+ * Error Handler Module
+ *
+ * Handles parsing HTTP error responses and converting them to typed exceptions.
+ */
+import { debugError } from '../debug-loggers.js';
+import { AuthenticationError, HerokuApiError, NotFoundError, RateLimitError, TwoFactorRequiredError, } from '../errors.js';
+/**
+ * Parse and handle an error response from the API
+ * Throws appropriate typed error based on status code
+ */
+export async function handleErrorResponse(response) {
+    let errorBody;
+    try {
+        const contentType = response.headers.get('content-type');
+        if (contentType?.includes('application/json')) {
+            errorBody = await response.json();
+        }
+    }
+    catch {
+        // Failed to parse error body, continue without it
+    }
+    debugError('Error response: %d %O', response.status, errorBody);
+    // Check for 2FA error (can be 403 or 412)
+    if (response.status === 412
+        || (response.status === 403 && errorBody?.id === 'two_factor')) {
+        throw new TwoFactorRequiredError(response, errorBody);
+    }
+    switch (response.status) {
+        case 401: {
+            throw new AuthenticationError(response, errorBody);
+        }
+        case 404: {
+            throw new NotFoundError(response, errorBody);
+        }
+        case 429: {
+            throw new RateLimitError(response, errorBody);
+        }
+        default: {
+            const message = errorBody?.message || `HTTP ${response.status}: ${response.statusText}`;
+            throw new HerokuApiError(message, response.status, response, errorBody);
+        }
+    }
+}

package/dist/client/http-request-hooks.d.ts

@@ -0,0 +1,18 @@
+/**
+ * HTTP Hooks Module
+ *
+ * Factory functions for creating beforeRequest and afterResponse hooks
+ * used by the ky HTTP client.
+ */
+import type { AfterResponseHook, BeforeRequestHook } from 'ky';
+import type { TwoFactorOptions } from '../types.js';
+/**
+ * Create a beforeRequest hook that adds authentication and custom headers
+ */
+export declare function createBeforeRequestHook(getToken: () => Promise<string | undefined>, defaultAccept: string | undefined, customHeaders?: Record<string, string>, debug?: boolean): BeforeRequestHook;
+/**
+ * Create an afterResponse hook that handles 2FA challenges and errors
+ */
+export declare function createAfterResponseHook(twoFactorOptions: TwoFactorOptions | undefined, twoFactorAttemptedRef: {
+    value: boolean;
+}): AfterResponseHook;

package/dist/client/http-request-hooks.js

@@ -0,0 +1,62 @@
+/**
+ * HTTP Hooks Module
+ *
+ * Factory functions for creating beforeRequest and afterResponse hooks
+ * used by the ky HTTP client.
+ */
+import { debugAuth, debugRequest, debugResponse } from '../debug-loggers.js';
+import { handleErrorResponse } from './http-error-handler.js';
+import { handle2FAChallenge, is2FAError } from './two-factor-authentication-handler.js';
+/**
+ * Create a beforeRequest hook that adds authentication and custom headers
+ */
+export function createBeforeRequestHook(getToken, defaultAccept, customHeaders, debug) {
+    return async ({ request }) => {
+        // Apply the service's default Accept header when the caller
+        // hasn't set one. Services that don't declare one (e.g. `custom`)
+        // skip this entirely.
+        if (defaultAccept && !request.headers.has('Accept')) {
+            request.headers.set('Accept', defaultAccept);
+        }
+        // Add custom headers from options
+        if (customHeaders) {
+            for (const [key, value] of Object.entries(customHeaders)) {
+                request.headers.set(key, value);
+            }
+        }
+        // Add authorization header
+        const token = await getToken();
+        if (token) {
+            request.headers.set('Authorization', `Bearer ${token}`);
+            debugAuth('Authorization header added');
+        }
+        debugRequest('%s %s', request.method, request.url);
+        if (debug) {
+            const headers = {};
+            // eslint-disable-next-line unicorn/no-array-for-each
+            request.headers.forEach((value, key) => {
+                headers[key] = value;
+            });
+            debugRequest('Headers: %O', headers);
+        }
+    };
+}
+/**
+ * Create an afterResponse hook that handles 2FA challenges and errors
+ */
+export function createAfterResponseHook(twoFactorOptions, twoFactorAttemptedRef) {
+    return async ({ request, response }) => {
+        debugResponse('%s %s -> %d', request.method, request.url, response.status);
+        // Handle 2FA challenge (can be 403 or 412)
+        const is2FAChallenge = response.status === 412
+            || (response.status === 403 && await is2FAError(response));
+        if (is2FAChallenge && twoFactorOptions && !twoFactorAttemptedRef.value) {
+            return handle2FAChallenge(request, twoFactorOptions, twoFactorAttemptedRef);
+        }
+        // Handle errors
+        if (!response.ok) {
+            await handleErrorResponse(response);
+        }
+        return response;
+    };
+}

package/dist/client/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 type { HerokuApiClientOptions, RequestOptions } from '../types.js';
+export declare class HerokuApiClient {
+    private clientPromise;
+    private kyOptions;
+    private options;
+    private tokenProvider?;
+    private twoFactorAttempted;
+    constructor(options?: HerokuApiClientOptions);
+    /**
+     * Make a DELETE request
+     */
+    delete(path: string, options?: RequestOptions): Promise<Response>;
+    /**
+     * Make a GET request
+     */
+    get(path: string, options?: RequestOptions): Promise<Response>;
+    /**
+     * Make a PATCH request
+     */
+    patch(path: string, body?: unknown, options?: RequestOptions): Promise<Response>;
+    /**
+     * Make a POST request
+     */
+    post(path: string, body?: unknown, options?: RequestOptions): Promise<Response>;
+    /**
+     * Make a PUT request
+     */
+    put(path: string, body?: unknown, options?: RequestOptions): Promise<Response>;
+    /**
+     * Set or update a client option
+     */
+    setOption<K extends keyof HerokuApiClientOptions>(key: K, value: HerokuApiClientOptions[K]): void;
+    /**
+     * Create a streaming request (returns the Response object for stream access)
+     */
+    stream(path: string, options?: RequestOptions): Promise<Response>;
+    /**
+     * Lazily construct ky with an env-aware undici dispatcher (Node)
+     * or no dispatcher (browser). Cached after the first call.
+     */
+    private getClient;
+    /**
+     * Get the authorization token
+     */
+    private getToken;
+    /**
+     * Make a request with full control over options
+     */
+    private request;
+}