@heroku/sdk 0.6.0 → 0.6.1

package/README.md

@@ -28,12 +28,42 @@ const favorites = await sdk.dashboardBackend.favorite.list({ type: 'app' })
 await sdk.platform.app.enableMaintenance('my-app')
 ```
 
+Extensions can also coordinate multiple services. For example, resolve a
+pipeline first, then resolve its GitHub repository through Repositories API
+with the Kolkrabbi-backed repositories service as a fallback:
+
+```ts
+import { HerokuSDK } from '@heroku/sdk'
+import { reviewAppConfigExtensions } from '@heroku/sdk/extensions/platform'
+
+const sdk = new HerokuSDK({ extensions: [reviewAppConfigExtensions] })
+const pipeline = await sdk.platform.pipeline.info('my-pipeline')
+
+if (!pipeline.id) throw new Error('Pipeline response did not include an id')
+const repo = await sdk.platform.reviewAppConfig.resolveRepoName(pipeline.id)
+```
+
 You can also pass options directly:
 
 ```ts
 const sdk = new HerokuSDK({ clientOptions: { token: 'your-api-token' } })
 ```
 
+Common client options apply to every service. In particular, a common `baseUrl`
+overrides every service's default host, including Metrics and Repositories. Use
+shallow per-service overrides when only specific services should use a host or
+other client setting:
+
+```ts
+const sdk = new HerokuSDK({
+  clientOptions: { token: 'your-api-token' },
+  clientOptionsByService: {
+    platform: { baseUrl: 'https://api.heroku.com' },
+    repositoriesApi: { baseUrl: 'https://api.heroku.com' },
+  },
+})
+```
+
 ### Per-service clients
 
 If you only need one service (and want the smallest possible bundle), import the factory directly. These return the same typed client the SDK class wraps internally.
@@ -44,12 +74,14 @@ import { createDataClient }         from '@heroku/sdk/data'
 import { createDashboardBackendClient } from '@heroku/sdk/dashboard-backend'
 import { createMetricsClient }      from '@heroku/sdk/metrics'
 import { createRepositoriesClient } from '@heroku/sdk/repositories'
+import { createRepositoriesApiClient } from '@heroku/sdk/repositories-api'
 
 const platform     = createPlatformClient()
 const data         = createDataClient()
 const dashboardBackend = createDashboardBackendClient()
 const metrics      = createMetricsClient()
 const repositories = createRepositoriesClient()
+const repositoriesApi = createRepositoriesApiClient()
 
 const apps = await platform.app.list()
 const favorites = await dashboardBackend.favorite.list({ type: 'app' })
@@ -65,6 +97,7 @@ const favorites = await dashboardBackend.favorite.list({ type: 'app' })
 | `createDashboardBackendClient`, `DashboardBackendClient` | `@heroku/sdk/dashboard-backend` |
 | `createMetricsClient`, `MetricsClient`   | `@heroku/sdk/metrics`             |
 | `createRepositoriesClient`, `RepositoriesClient` | `@heroku/sdk/repositories` |
+| `createRepositoriesApiClient`, `RepositoriesApiClient` | `@heroku/sdk/repositories-api` |
 | `appExtensions`, `dynoExtensions`, …     | `@heroku/sdk/extensions/platform` |
 | `databaseExtensions`, …                  | `@heroku/sdk/extensions/data`     |
 

package/dist/core/extend-resource.d.ts

@@ -2,15 +2,20 @@ import type { DashboardBackendClient } from '../services/dashboard-backend.js';
 import type { DataClient } from '../services/data.js';
 import type { MetricsClient } from '../services/metrics.js';
 import type { PlatformClient } from '../services/platform.js';
+import type { RepositoriesApiClient } from '../services/repositories-api.js';
 import type { RepositoriesClient } from '../services/repositories.js';
-export type ServiceName = 'dashboardBackend' | 'data' | 'metrics' | 'platform' | 'repositories';
-export type ResourceCtx = {
+export type ServiceName = 'dashboardBackend' | 'data' | 'metrics' | 'platform' | 'repositories' | 'repositoriesApi';
+type BaseResourceCtx = {
     dashboardBackend: DashboardBackendClient;
     data: DataClient;
     metrics: MetricsClient;
     platform: PlatformClient;
     repositories: RepositoriesClient;
 };
+export type ResourceCtx = BaseResourceCtx & {
+    /** Available to SDK-provided extensions; optional for compatibility with existing extension contexts. */
+    repositoriesApi?: RepositoriesApiClient;
+};
 export type ResourceMethods = Record<string, (...args: any[]) => any>;
 export type ResourceExtension<S extends ServiceName = ServiceName, R extends string = string, M extends ResourceMethods = ResourceMethods> = {
     factory: (ctx: ResourceCtx) => M;

package/dist/core/heroku-sdk.d.ts

@@ -3,10 +3,16 @@ import type { DashboardBackendClient } from '../services/dashboard-backend.js';
 import type { DataClient } from '../services/data.js';
 import type { MetricsClient } from '../services/metrics.js';
 import type { PlatformClient } from '../services/platform.js';
+import type { RepositoriesApiClient } from '../services/repositories-api.js';
 import type { RepositoriesClient } from '../services/repositories.js';
-import type { ApplyExtensions, ExtensionsFor, ResourceExtension } from './extend-resource.js';
+import type { ApplyExtensions, ExtensionsFor, ResourceExtension, ServiceName } from './extend-resource.js';
+type ServiceClientOptions = Omit<HerokuApiClientOptions, 'service'> & {
+    service?: never;
+};
 export type HerokuSDKOptions<Exts extends readonly ResourceExtension[]> = {
     clientOptions?: HerokuApiClientOptions;
+    /** Shallow per-service overrides applied after common clientOptions. */
+    clientOptionsByService?: Partial<Record<ServiceName, ServiceClientOptions>>;
     extensions?: Exts;
 };
 export declare class HerokuSDK<const Exts extends readonly ResourceExtension[] = readonly ResourceExtension[]> {
@@ -17,4 +23,6 @@ export declare class HerokuSDK<const Exts extends readonly ResourceExtension[] =
     get metrics(): ApplyExtensions<MetricsClient, ExtensionsFor<Exts, 'metrics'>>;
     get platform(): ApplyExtensions<PlatformClient, ExtensionsFor<Exts, 'platform'>>;
     get repositories(): ApplyExtensions<RepositoriesClient, ExtensionsFor<Exts, 'repositories'>>;
+    get repositoriesApi(): ApplyExtensions<RepositoriesApiClient, ExtensionsFor<Exts, 'repositoriesApi'>>;
 }
+export {};

package/dist/core/heroku-sdk.js

@@ -2,6 +2,7 @@ import { createDashboardBackendClient } from '../services/dashboard-backend.js';
 import { createDataClient } from '../services/data.js';
 import { createMetricsClient } from '../services/metrics.js';
 import { createPlatformClient } from '../services/platform.js';
+import { createRepositoriesApiClient } from '../services/repositories-api.js';
 import { createRepositoriesClient } from '../services/repositories.js';
 import { mergeExtensions } from './extensions-proxy.js';
 function partitionByService(extensions) {
@@ -15,6 +16,7 @@ function partitionByService(extensions) {
 }
 export class HerokuSDK {
     #clientOptions;
+    #clientOptionsByService;
     #ctx;
     #dashboardBackend;
     #data;
@@ -26,9 +28,12 @@ export class HerokuSDK {
     #rawMetrics;
     #rawPlatform;
     #rawRepositories;
+    #rawRepositoriesApi;
     #repositories;
+    #repositoriesApi;
     constructor(options = {}) {
         this.#clientOptions = options.clientOptions ?? {};
+        this.#clientOptionsByService = options.clientOptionsByService ?? {};
         this.#extensionsByService = partitionByService(options.extensions ?? []);
     }
     get dashboardBackend() {
@@ -51,6 +56,19 @@ export class HerokuSDK {
         this.#repositories ??= mergeExtensions(this.#getRawRepositories(), this.#extensionsByService.get('repositories') ?? [], this.#getCtx());
         return this.#repositories;
     }
+    get repositoriesApi() {
+        this.#repositoriesApi ??= mergeExtensions(this.#getRawRepositoriesApi(), this.#extensionsByService.get('repositoriesApi') ?? [], this.#getCtx());
+        return this.#repositoriesApi;
+    }
+    #getClientOptions(service) {
+        const serviceOverride = this.#clientOptionsByService[service];
+        const serviceOptions = { ...serviceOverride };
+        delete serviceOptions.service;
+        return {
+            ...this.#clientOptions,
+            ...serviceOptions,
+        };
+    }
     #getCtx() {
         this.#ctx ??= Object.defineProperties({}, {
             dashboardBackend: {
@@ -73,27 +91,35 @@ export class HerokuSDK {
                 enumerable: true,
                 get: () => this.#getRawRepositories(),
             },
+            repositoriesApi: {
+                enumerable: true,
+                get: () => this.#getRawRepositoriesApi(),
+            },
         });
         return this.#ctx;
     }
     #getRawDashboardBackend() {
-        this.#rawDashboardBackend ??= createDashboardBackendClient(this.#clientOptions);
+        this.#rawDashboardBackend ??= createDashboardBackendClient(this.#getClientOptions('dashboardBackend'));
         return this.#rawDashboardBackend;
     }
     #getRawData() {
-        this.#rawData ??= createDataClient(this.#clientOptions);
+        this.#rawData ??= createDataClient(this.#getClientOptions('data'));
         return this.#rawData;
     }
     #getRawMetrics() {
-        this.#rawMetrics ??= createMetricsClient(this.#clientOptions);
+        this.#rawMetrics ??= createMetricsClient(this.#getClientOptions('metrics'));
         return this.#rawMetrics;
     }
     #getRawPlatform() {
-        this.#rawPlatform ??= createPlatformClient(this.#clientOptions);
+        this.#rawPlatform ??= createPlatformClient(this.#getClientOptions('platform'));
         return this.#rawPlatform;
     }
     #getRawRepositories() {
-        this.#rawRepositories ??= createRepositoriesClient(this.#clientOptions);
+        this.#rawRepositories ??= createRepositoriesClient(this.#getClientOptions('repositories'));
         return this.#rawRepositories;
     }
+    #getRawRepositoriesApi() {
+        this.#rawRepositoriesApi ??= createRepositoriesApiClient(this.#getClientOptions('repositoriesApi'));
+        return this.#rawRepositoriesApi;
+    }
 }

package/dist/resources/extensions/platform.d.ts

@@ -7,6 +7,7 @@ export { type AttachmentAttachedEvent, type AttachmentDetachedEvent, type Attach
 export { pipelineCouplingExtensions } from '../platform/pipeline/coupling.js';
 export { pipelineExtensions } from '../platform/pipeline/index.js';
 export { pipelinePromotionExtensions } from '../platform/pipeline/promotion.js';
+export { type ResolveRepoNameOptions, reviewAppConfigExtensions } from '../platform/review-app-config/index.js';
 export { privateToShield, shieldToPrivate } from '../platform/shield.js';
 export { createAndAssociate, type CreateAndAssociateOptions, sniEndpointExtensions } from '../platform/sni-endpoint/index.js';
 export { spaceExtensions, SpaceNotAllocatedError, SpaceNotReadyError, type SpaceOptions, type SpaceWithNat, waitForAllocated, type WaitForAllocatedOptions, } from '../platform/space/index.js';

package/dist/resources/extensions/platform.js

@@ -7,6 +7,7 @@ export { logSessionExtensions, parseHerokuLogLine, } from '../platform/log-sessi
 export { pipelineCouplingExtensions } from '../platform/pipeline/coupling.js';
 export { pipelineExtensions } from '../platform/pipeline/index.js';
 export { pipelinePromotionExtensions } from '../platform/pipeline/promotion.js';
+export { reviewAppConfigExtensions } from '../platform/review-app-config/index.js';
 export { privateToShield, shieldToPrivate } from '../platform/shield.js';
 export { createAndAssociate, sniEndpointExtensions } from '../platform/sni-endpoint/index.js';
 export { spaceExtensions, SpaceNotAllocatedError, SpaceNotReadyError, waitForAllocated, } from '../platform/space/index.js';

package/dist/resources/platform/review-app-config/debug.d.ts

@@ -0,0 +1,2 @@
+import createDebug from 'debug';
+export declare const debug: createDebug.Debugger;

package/dist/resources/platform/review-app-config/debug.js

@@ -0,0 +1,2 @@
+import createDebug from 'debug';
+export const debug = createDebug('heroku:sdk:resources:review-app-config');

package/dist/resources/platform/review-app-config/index.d.ts

@@ -0,0 +1,5 @@
+import { type ResolveRepoNameOptions } from './resolve-repo-name.js';
+export { resolveRepoName, type ResolveRepoNameOptions } from './resolve-repo-name.js';
+export declare const reviewAppConfigExtensions: import("../../../core/extend-resource.js").ResourceExtension<"platform", "reviewAppConfig", {
+    resolveRepoName: (pipelineId: string, options?: ResolveRepoNameOptions) => Promise<string>;
+}>;

package/dist/resources/platform/review-app-config/index.js

@@ -0,0 +1,17 @@
+import { extendResource } from '../../../core/extend-resource.js';
+import { resolveRepoName } from './resolve-repo-name.js';
+export { resolveRepoName } from './resolve-repo-name.js';
+export const reviewAppConfigExtensions = extendResource('platform', 'reviewAppConfig', ctx => {
+    const { repositoriesApi } = ctx;
+    if (!repositoriesApi) {
+        throw new Error('reviewAppConfigExtensions requires ResourceCtx.repositoriesApi');
+    }
+    const resolveRepoNameCtx = {
+        platform: ctx.platform,
+        repositories: ctx.repositories,
+        repositoriesApi,
+    };
+    return {
+        resolveRepoName: (pipelineId, options) => resolveRepoName(resolveRepoNameCtx, pipelineId, options),
+    };
+});

package/dist/resources/platform/review-app-config/resolve-repo-name.d.ts

@@ -0,0 +1,16 @@
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+type ResolveRepoNameCtx = Pick<ResourceCtx, 'platform' | 'repositories'> & {
+    repositoriesApi: NonNullable<ResourceCtx['repositoriesApi']>;
+};
+export type ResolveRepoNameOptions = {
+    signal?: AbortSignal;
+};
+/**
+ * Resolves the GitHub repository name for a canonical pipeline ID.
+ * Resolve user-supplied pipeline names before calling this helper.
+ * Uses Repositories API when the account feature is enabled, and falls back
+ * to the Kolkrabbi-backed repositories service when the feature is disabled,
+ * the feature lookup fails, or Repositories API cannot return a usable name.
+ */
+export declare function resolveRepoName(ctx: ResolveRepoNameCtx, pipelineId: string, options?: ResolveRepoNameOptions): Promise<string>;
+export {};

package/dist/resources/platform/review-app-config/resolve-repo-name.js

@@ -0,0 +1,54 @@
+import { debug } from './debug.js';
+/**
+ * Resolves the GitHub repository name for a canonical pipeline ID.
+ * Resolve user-supplied pipeline names before calling this helper.
+ * Uses Repositories API when the account feature is enabled, and falls back
+ * to the Kolkrabbi-backed repositories service when the feature is disabled,
+ * the feature lookup fails, or Repositories API cannot return a usable name.
+ */
+export async function resolveRepoName(ctx, pipelineId, options = {}) {
+    const { signal } = options;
+    signal?.throwIfAborted();
+    const platform = signal ? ctx.platform.withOptions({ signal }) : ctx.platform;
+    let useRepositoriesApi;
+    try {
+        const feature = await platform.accountFeature.info('dashboard-repositories-api');
+        signal?.throwIfAborted();
+        useRepositoriesApi = feature.enabled;
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        debug('feature lookup failed error=%s; falling back', describeError(error));
+    }
+    if (useRepositoriesApi) {
+        try {
+            const repositoriesApi = signal ? ctx.repositoriesApi.withOptions({ signal }) : ctx.repositoriesApi;
+            const repository = await repositoriesApi.githubRepository.info(pipelineId);
+            signal?.throwIfAborted();
+            const repositoryName = repository.full_name?.trim();
+            if (repositoryName) {
+                return repositoryName;
+            }
+            debug('repositories API returned no full name; falling back');
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            debug('repositories API lookup failed error=%s; falling back', describeError(error));
+        }
+    }
+    else if (useRepositoriesApi === false) {
+        signal?.throwIfAborted();
+        debug('repositories API disabled; falling back');
+    }
+    const repositories = signal ? ctx.repositories.withOptions({ signal }) : ctx.repositories;
+    const pipelineRepository = await repositories.pipelineRepository.info(pipelineId);
+    signal?.throwIfAborted();
+    const repositoryName = pipelineRepository.repository.name.trim();
+    if (!repositoryName) {
+        throw new Error('Repositories service returned no repository name');
+    }
+    return repositoryName;
+}
+function describeError(error) {
+    return error instanceof Error ? error.name : typeof error;
+}

package/dist/services/repositories-api.d.ts

@@ -0,0 +1,5 @@
+import type { HerokuApiClientOptions } from '@heroku/heroku-fetch';
+import type { HerokuClient } from '@heroku/types/repositories-api';
+import type { RoutesClientExtras } from '../core/create-client.js';
+export type RepositoriesApiClient = HerokuClient & RoutesClientExtras<HerokuClient>;
+export declare function createRepositoriesApiClient(options?: HerokuApiClientOptions): RepositoriesApiClient;

package/dist/services/repositories-api.js

@@ -0,0 +1,10 @@
+import * as routes from '@heroku/types/repositories-api/routes';
+import { createClient } from '../core/create-client.js';
+const REPOSITORIES_API_ACCEPT = 'application/vnd.heroku+json; version=3.repositories-api';
+export function createRepositoriesApiClient(options = {}) {
+    return createClient(routes, {
+        defaultAccept: REPOSITORIES_API_ACCEPT,
+        service: 'platform',
+        ...options,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heroku/sdk",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Heroku SDK",
   "author": "Heroku",
   "type": "module",
@@ -30,6 +30,10 @@
       "types": "./dist/services/repositories.d.ts",
       "default": "./dist/services/repositories.js"
     },
+    "./repositories-api": {
+      "types": "./dist/services/repositories-api.d.ts",
+      "default": "./dist/services/repositories-api.js"
+    },
     "./extensions/platform": {
       "types": "./dist/resources/extensions/platform.d.ts",
       "default": "./dist/resources/extensions/platform.js"
@@ -70,6 +74,10 @@
       "types": "./dist/resources/platform/pipeline/*.d.ts",
       "default": "./dist/resources/platform/pipeline/*.js"
     },
+    "./resources/platform/review-app-config": {
+      "types": "./dist/resources/platform/review-app-config/index.d.ts",
+      "default": "./dist/resources/platform/review-app-config/index.js"
+    },
     "./resources/platform/sni-endpoint": {
       "types": "./dist/resources/platform/sni-endpoint/index.d.ts",
       "default": "./dist/resources/platform/sni-endpoint/index.js"
@@ -108,7 +116,8 @@
     "lint:fix": "eslint --fix",
     "prebuild": "rimraf dist",
     "prepare": "npm run build",
-    "test": "vitest --run"
+    "test": "vitest --run",
+    "test:types": "tsc --noEmit -p tsconfig.type-tests.json"
   },
   "license": "Apache-2.0",
   "engines": {
@@ -132,7 +141,7 @@
   },
   "dependencies": {
     "@heroku/heroku-fetch": "^0.1.4",
-    "@heroku/types": "^4.3.0",
+    "@heroku/types": "^4.7.0",
     "debug": "^4.4.0"
   }
 }