@heroku/heroku-cli-util 10.0.0-beta.2 → 10.1.0

package/README.md

@@ -102,7 +102,7 @@ try {
 
 // PG types (for TypeScript)
 /**
- * types.pg.AddOnAttachmentWithConfigVarsAndPlan
+ * types.pg.ExtendedAddonAttachment
  * types.pg.AddOnWithRelatedData
  * types.pg.ConnectionDetails
  * types.pg.ConnectionDetailsWithAttachment

package/dist/errors/ambiguous.d.ts

@@ -0,0 +1,16 @@
+import type { ExtendedAddonAttachment } from '../types/pg/data-api.js';
+/**
+ * This error is used internally to signal when the `AddonAttachmentResolver` cannot resolve
+ * to a single attachment.
+ */
+export declare class AmbiguousError extends Error {
+    readonly matches: ExtendedAddonAttachment[];
+    readonly type: string;
+    readonly body: {
+        id: string;
+        message: string;
+    };
+    readonly message: string;
+    readonly statusCode = 422;
+    constructor(matches: ExtendedAddonAttachment[], type: string);
+}

package/dist/{types/errors → errors}/ambiguous.js

@@ -1,3 +1,7 @@
+/**
+ * This error is used internally to signal when the `AddonAttachmentResolver` cannot resolve
+ * to a single attachment.
+ */
 export class AmbiguousError extends Error {
     matches;
     type;

package/dist/errors/not-found.d.ts

@@ -0,0 +1,20 @@
+/**
+ * This error is used only when the Platform API add-on attachment resolver resolves to one or more matches, but
+ * a namespace (credential name) was provided and none of them had that exact namespace.
+ *
+ * We would've expected this to use the same error message the resolver returns when it throws a Not Found error:
+ * `"Couldn't find that add on attachment."`, because it's attachments and not add-ons that are being resolved.
+ *
+ * However, that's not the case here and we cannot refactor this to use the expected messaging because the only
+ * command checking credentials, `pg:psql`, has a check with a strict match on the error message text to change
+ * the error displayed to the user
+ * ([see here](https://github.com/heroku/cli/blob/b79f2c93d6f21eafd9d93983bcd377e4bc7f8438/packages/cli/src/commands/pg/psql.ts#L32)).
+ */
+export declare class NotFound extends Error {
+    readonly body: {
+        id: string;
+        message: string;
+    };
+    readonly message = "Couldn't find that addon.";
+    readonly statusCode = 404;
+}

package/dist/errors/not-found.js

@@ -0,0 +1,17 @@
+/**
+ * This error is used only when the Platform API add-on attachment resolver resolves to one or more matches, but
+ * a namespace (credential name) was provided and none of them had that exact namespace.
+ *
+ * We would've expected this to use the same error message the resolver returns when it throws a Not Found error:
+ * `"Couldn't find that add on attachment."`, because it's attachments and not add-ons that are being resolved.
+ *
+ * However, that's not the case here and we cannot refactor this to use the expected messaging because the only
+ * command checking credentials, `pg:psql`, has a check with a strict match on the error message text to change
+ * the error displayed to the user
+ * ([see here](https://github.com/heroku/cli/blob/b79f2c93d6f21eafd9d93983bcd377e4bc7f8438/packages/cli/src/commands/pg/psql.ts#L32)).
+ */
+export class NotFound extends Error {
+    body = { id: 'not_found', message: 'Couldn\'t find that addon.' };
+    message = 'Couldn\'t find that addon.';
+    statusCode = 404;
+}

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { AmbiguousError } from './types/errors/ambiguous.js';
-import { NotFound } from './types/errors/not-found.js';
-import { AddOnAttachmentWithConfigVarsAndPlan, AddOnWithRelatedData, Link } from './types/pg/data-api.js';
+import { APIClient } from '@heroku-cli/command';
+import { AmbiguousError } from './errors/ambiguous.js';
+import { NotFound } from './errors/not-found.js';
+import { AddOnWithRelatedData, ExtendedAddonAttachment, Link } from './types/pg/data-api.js';
 import { ConnectionDetails, ConnectionDetailsWithAttachment, TunnelConfig } from './types/pg/tunnel.js';
-import { getDatabase } from './utils/pg/databases.js';
+import DatabaseResolver from './utils/pg/databases.js';
 import getHost from './utils/pg/host.js';
-import { exec } from './utils/pg/psql.js';
 import { prompt } from './ux/prompt.js';
 import { styledHeader } from './ux/styled-header.js';
 import { styledJSON } from './ux/styled-json.js';
@@ -12,25 +12,28 @@ import { styledObject } from './ux/styled-object.js';
 import { table } from './ux/table.js';
 import { wait } from './ux/wait.js';
 export declare const types: {
-    errors: {
-        AmbiguousError: typeof AmbiguousError;
-        NotFound: typeof NotFound;
-    };
     pg: {
-        AddOnAttachmentWithConfigVarsAndPlan: AddOnAttachmentWithConfigVarsAndPlan;
         AddOnWithRelatedData: AddOnWithRelatedData;
         ConnectionDetails: ConnectionDetails;
         ConnectionDetailsWithAttachment: ConnectionDetailsWithAttachment;
+        ExtendedAddonAttachment: ExtendedAddonAttachment;
         Link: Link;
         TunnelConfig: TunnelConfig;
     };
 };
 export declare const utils: {
+    errors: {
+        AmbiguousError: typeof AmbiguousError;
+        NotFound: typeof NotFound;
+    };
     pg: {
-        databases: typeof getDatabase;
+        DatabaseResolver: typeof DatabaseResolver;
+        fetcher: {
+            database(heroku: APIClient, appId: string, attachmentId?: string, namespace?: string): Promise<ConnectionDetailsWithAttachment>;
+        };
         host: typeof getHost;
         psql: {
-            exec: typeof exec;
+            exec(connectionDetails: ConnectionDetailsWithAttachment, query: string, psqlCmdArgs?: string[]): Promise<string>;
         };
     };
 };

package/dist/index.js

@@ -1,8 +1,8 @@
-import { AmbiguousError } from './types/errors/ambiguous.js';
-import { NotFound } from './types/errors/not-found.js';
-import { getDatabase } from './utils/pg/databases.js';
+import { AmbiguousError } from './errors/ambiguous.js';
+import { NotFound } from './errors/not-found.js';
+import DatabaseResolver from './utils/pg/databases.js';
 import getHost from './utils/pg/host.js';
-import { exec } from './utils/pg/psql.js';
+import PsqlService from './utils/pg/psql.js';
 import { confirm } from './ux/confirm.js';
 import { prompt } from './ux/prompt.js';
 import { styledHeader } from './ux/styled-header.js';
@@ -11,25 +11,34 @@ import { styledObject } from './ux/styled-object.js';
 import { table } from './ux/table.js';
 import { wait } from './ux/wait.js';
 export const types = {
-    errors: {
-        AmbiguousError,
-        NotFound,
-    },
     pg: {
-        AddOnAttachmentWithConfigVarsAndPlan: {},
         AddOnWithRelatedData: {},
         ConnectionDetails: {},
         ConnectionDetailsWithAttachment: {},
+        ExtendedAddonAttachment: {},
         Link: {},
         TunnelConfig: {},
     },
 };
 export const utils = {
+    errors: {
+        AmbiguousError,
+        NotFound, // This should be NotFoundError for consistency, but we're keeping it for backwards compatibility
+    },
     pg: {
-        databases: getDatabase,
+        DatabaseResolver,
+        fetcher: {
+            database(heroku, appId, attachmentId, namespace) {
+                const databaseResolver = new DatabaseResolver(heroku);
+                return databaseResolver.getDatabase(appId, attachmentId, namespace);
+            },
+        },
         host: getHost,
         psql: {
-            exec,
+            exec(connectionDetails, query, psqlCmdArgs = []) {
+                const psqlService = new PsqlService(connectionDetails);
+                return psqlService.execQuery(query, psqlCmdArgs);
+            },
         },
     },
 };

package/dist/types/pg/data-api.d.ts

@@ -1,13 +1,41 @@
 import * as Heroku from '@heroku-cli/schema';
+type DeepRequired<T> = T extends object ? {
+    [K in keyof T]-?: DeepRequired<T[K]>;
+} : T;
+/**
+ * This is the base type for the property `addon` on an `AddOnAttachment` as described in the Platform API Reference.
+ */
+type AddonDescriptor = DeepRequired<Heroku.AddOnAttachment>['addon'];
+/**
+ * This is the modified type for the `addon` property when the request to Platform API includes the value `addon:plan`
+ * in the `Accept-Inclusion` header.
+ */
+type AddonDescriptorWithPlanInclusion = {
+    plan: {
+        id: string;
+        name: string;
+    };
+} & AddonDescriptor;
+/**
+ * This is the modified type for the `AddOnAttachment` type when the request to Platform API includes the value
+ * `config_vars` in the `Accept-Inclusion` header.
+ */
+type AddonAttachmentWithConfigVarsInclusion = {
+    config_vars: string[];
+} & DeepRequired<Heroku.AddOnAttachment>;
+/**
+ * This is the modified type for the `AddOnAttachment` we use on these lib functions because all requests made to
+ * Platform API to get add-on attachments, either through the Add-on Attachment List endpoint or the
+ * add-on attachment resolver action endpoint, include the header `Accept-Inclusion: addon:plan,config_vars`.
+ */
+export type ExtendedAddonAttachment = {
+    addon: AddonDescriptorWithPlanInclusion;
+} & AddonAttachmentWithConfigVarsInclusion;
 export type AddOnWithRelatedData = {
     attachment_names?: string[];
     links?: Link[];
-    plan: Required<Heroku.AddOn['plan']>;
-} & Required<Heroku.AddOnAttachment['addon']>;
-export type AddOnAttachmentWithConfigVarsAndPlan = {
-    addon: AddOnWithRelatedData;
-    config_vars: Heroku.AddOn['config_vars'];
-} & Required<Heroku.AddOnAttachment>;
+    plan: DeepRequired<Heroku.AddOn['plan']>;
+} & AddonDescriptor;
 export type Link = {
     attachment_name?: string;
     created_at: string;
@@ -15,3 +43,4 @@ export type Link = {
     name: string;
     remote?: Link;
 };
+export {};

package/dist/types/pg/tunnel.d.ts

@@ -1,11 +1,8 @@
-import type { AddOnAttachment } from '@heroku-cli/schema';
 import { Server } from 'node:net';
 import * as createTunnel from 'tunnel-ssh';
-import type { AddOnAttachmentWithConfigVarsAndPlan } from './data-api.js';
+import type { ExtendedAddonAttachment } from './data-api.js';
 export type ConnectionDetails = {
     _tunnel?: Server;
-    bastionHost?: string;
-    bastionKey?: string;
     database: string;
     host: string;
     password: string;
@@ -13,10 +10,16 @@ export type ConnectionDetails = {
     port: string;
     url: string;
     user: string;
-};
+} & BastionConfig;
 export type ConnectionDetailsWithAttachment = {
-    attachment: Required<{
-        addon: AddOnAttachmentWithConfigVarsAndPlan;
-    } & AddOnAttachment>;
+    attachment: ExtendedAddonAttachment;
 } & ConnectionDetails;
 export type TunnelConfig = createTunnel.Config;
+export interface BastionConfigResponse {
+    host: string;
+    private_key: string;
+}
+export type BastionConfig = {
+    bastionHost?: string;
+    bastionKey?: string;
+};

package/dist/utils/addons/resolve.d.ts

@@ -1,9 +1,13 @@
 import type { APIClient } from '@heroku-cli/command';
-import type { AddOnAttachment } from '@heroku-cli/schema';
-import type { AddOnAttachmentWithConfigVarsAndPlan } from '../../types/pg/data-api.js';
-export declare const appAttachment: (heroku: APIClient, app: string | undefined, id: string, options?: {
-    addon_service?: string;
+import type { ExtendedAddonAttachment } from '../../types/pg/data-api.js';
+export interface AddonAttachmentResolverOptions {
+    addonService?: string;
     namespace?: string;
-}) => Promise<{
-    addon: AddOnAttachmentWithConfigVarsAndPlan;
-} & AddOnAttachment>;
+}
+export default class AddonAttachmentResolver {
+    private readonly heroku;
+    private readonly attachmentHeaders;
+    constructor(heroku: APIClient);
+    resolve(appId: string | undefined, attachmentId: string, options?: AddonAttachmentResolverOptions): Promise<ExtendedAddonAttachment>;
+    private singularize;
+}

package/dist/utils/addons/resolve.js

@@ -1,24 +1,33 @@
-import { AmbiguousError } from '../../types/errors/ambiguous.js';
-import { NotFound } from '../../types/errors/not-found.js';
-export const appAttachment = async (heroku, app, id, options = {}) => {
-    const result = await heroku.post('/actions/addon-attachments/resolve', {
-        // eslint-disable-next-line camelcase
-        body: { addon_attachment: id, addon_service: options.addon_service, app }, headers: attachmentHeaders,
-    });
-    return singularize('addon_attachment', options.namespace)(result.body);
-};
-const attachmentHeaders = {
-    Accept: 'application/vnd.heroku+json; version=3.sdk',
-    'Accept-Inclusion': 'addon:plan,config_vars',
-};
-function singularize(type, namespace) {
-    return (matches) => {
+import { AmbiguousError } from '../../errors/ambiguous.js';
+import { NotFound } from '../../errors/not-found.js';
+export default class AddonAttachmentResolver {
+    heroku;
+    attachmentHeaders = {
+        Accept: 'application/vnd.heroku+json; version=3.sdk',
+        'Accept-Inclusion': 'addon:plan,config_vars',
+    };
+    constructor(heroku) {
+        this.heroku = heroku;
+    }
+    async resolve(appId, attachmentId, options = {}) {
+        const { body: attachments } = await this.heroku.post('/actions/addon-attachments/resolve', {
+            // eslint-disable-next-line camelcase
+            body: { addon_attachment: attachmentId, addon_service: options.addonService, app: appId },
+            headers: this.attachmentHeaders,
+        });
+        return this.singularize(attachments, options.namespace);
+    }
+    singularize(attachments, namespace) {
+        let matches;
         if (namespace) {
-            matches = matches.filter(m => m.namespace === namespace);
+            matches = attachments.filter(m => m.namespace === namespace);
+        }
+        else if (attachments.length > 1) {
+            // In cases that aren't specific enough, keep only attachments without a namespace
+            matches = attachments.filter(m => !Reflect.has(m, 'namespace') || m.namespace === null);
         }
-        else if (matches.length > 1) {
-            // In cases that aren't specific enough, filter by namespace
-            matches = matches.filter(m => !Reflect.has(m, 'namespace') || m.namespace === null);
+        else {
+            matches = attachments;
         }
         switch (matches.length) {
             case 0: {
@@ -28,8 +37,8 @@ function singularize(type, namespace) {
                 return matches[0];
             }
             default: {
-                throw new AmbiguousError(matches, type ?? '');
+                throw new AmbiguousError(matches, 'addon_attachment');
             }
         }
-    };
+    }
 }

package/dist/utils/pg/bastion.d.ts

@@ -1,30 +1,62 @@
 import type { APIClient } from '@heroku-cli/command';
+import { Server } from 'node:net';
 import * as createTunnel from 'tunnel-ssh';
-import { AddOnAttachmentWithConfigVarsAndPlan } from '../../types/pg/data-api.js';
-import { ConnectionDetails } from '../../types/pg/tunnel.js';
-import { TunnelConfig } from '../../types/pg/tunnel.js';
-export declare const bastionKeyPlan: (a: AddOnAttachmentWithConfigVarsAndPlan) => boolean;
-export declare const env: (db: ConnectionDetails) => {
-    TZ?: string;
-    PGAPPNAME: string;
-    PGSSLMODE: string;
-};
-export declare function fetchConfig(heroku: APIClient, db: {
-    id: string;
-}): Promise<import("@heroku/http-call").HTTP<{
-    host: string;
-    private_key: string;
-}>>;
-export declare const getBastion: (config: Record<string, string>, baseName: string) => {
-    bastionHost: string;
-    bastionKey: string;
-} | {
-    bastionHost?: undefined;
-    bastionKey?: undefined;
-};
-export declare function getConfigs(db: ConnectionDetails): {
+import { ExtendedAddonAttachment } from '../../types/pg/data-api.js';
+import { BastionConfig, ConnectionDetailsWithAttachment, TunnelConfig } from '../../types/pg/tunnel.js';
+/**
+ * Determines whether the attachment belongs to an add-on installed onto a non-shield Private Space.
+ * If true, the bastion information needs to be fetched from the Data API.
+ * For add-ons installed onto a Shield Private Space, the bastion information should be fetched from config vars.
+ *
+ * @param attachment - The add-on attachment to check
+ * @returns True if the attachment belongs to a non-shield Private Space, false otherwise
+ */
+export declare function bastionKeyPlan(attachment: ExtendedAddonAttachment): boolean;
+/**
+ * Fetches the bastion configuration from the Data API (only relevant for add-ons installed onto a
+ * non-shield Private Space).
+ * For add-ons installed onto a Shield Private Space, the bastion information is stored in the config vars.
+ *
+ * @param heroku - The Heroku API client
+ * @param addon - The add-on information
+ * @returns Promise that resolves to the bastion configuration
+ */
+export declare function fetchBastionConfig(heroku: APIClient, addon: ExtendedAddonAttachment['addon']): Promise<BastionConfig>;
+/**
+ * Returns the bastion configuration from the config vars for add-ons installed onto Shield
+ * Private Spaces.
+ *
+ * If there are bastions, extracts a host and a key from the config vars.
+ * If there are no bastions, returns an empty Object.
+ *
+ * We assert that _BASTIONS and _BASTION_KEY always exist together.
+ * If either is falsy, pretend neither exist.
+ *
+ * @param config - The configuration variables object
+ * @param baseName - The base name for the configuration variables
+ * @returns The bastion configuration object
+ */
+export declare const getBastionConfig: (config: Record<string, string>, baseName: string) => BastionConfig;
+/**
+ * Returns both the required environment variables to effect the psql command execution and the tunnel
+ * configuration according to the database connection details.
+ *
+ * @param connectionDetails - The database connection details with attachment information
+ * @returns Object containing database environment variables and tunnel configuration
+ */
+export declare function getPsqlConfigs(connectionDetails: ConnectionDetailsWithAttachment): {
     dbEnv: NodeJS.ProcessEnv;
     dbTunnelConfig: createTunnel.Config;
 };
-export declare function sshTunnel(db: ConnectionDetails, dbTunnelConfig: TunnelConfig, timeout?: number): Promise<void | import("net").Server | null>;
-export declare function tunnelConfig(db: ConnectionDetails): TunnelConfig;
+export type PsqlConfigs = ReturnType<typeof getPsqlConfigs>;
+/**
+ * Establishes an SSH tunnel to the database using the provided configuration.
+ *
+ * @param connectionDetails - The database connection details with attachment information
+ * @param dbTunnelConfig - The tunnel configuration object
+ * @param timeout - The timeout in milliseconds (default: 10000)
+ * @param createSSHTunnel - The function to create the SSH tunnel (default: promisified createTunnel.default)
+ * @returns Promise that resolves to the tunnel server or null if no bastion key is provided
+ * @throws Error if unable to establish the tunnel
+ */
+export declare function sshTunnel(connectionDetails: ConnectionDetailsWithAttachment, dbTunnelConfig: TunnelConfig, timeout?: number, createSSHTunnel?: (arg1: createTunnel.Config | undefined) => Promise<Server>): Promise<Server | void>;