@shipfox/api-integration-github 12.3.0 → 12.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-github",
   "license": "MIT",
-  "version": "12.3.0",
+  "version": "12.5.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -28,7 +28,7 @@
     "octokit": "^5.0.3",
     "zod": "^4.4.3",
     "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-integration-spi": "1.1.0",
+    "@shipfox/api-integration-spi": "1.1.1",
     "@shipfox/api-integration-github-dto": "12.2.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-drizzle": "0.3.5",

package/src/api/client.test.ts

@@ -1,9 +1,19 @@
 import {GithubIntegrationProviderError} from '#core/errors.js';
-import {createGithubApiClient} from './client.js';
+import {createGithubApiClient, mapGithubError} from './client.js';
 
-const {createInstallationAccessTokenMock} = vi.hoisted(() => ({
-  createInstallationAccessTokenMock: vi.fn(),
-}));
+const {createInstallationAccessTokenMock, RequestErrorMock} = vi.hoisted(() => {
+  class RequestErrorMock extends Error {
+    constructor(
+      message: string,
+      public readonly status: number,
+    ) {
+      super(message);
+      this.name = 'HttpError';
+    }
+  }
+
+  return {createInstallationAccessTokenMock: vi.fn(), RequestErrorMock};
+});
 
 vi.mock('octokit', () => ({
   App: class App {
@@ -16,9 +26,35 @@ vi.mock('octokit', () => ({
       return {defaults: options};
     },
   },
-  RequestError: class RequestError extends Error {},
+  RequestError: RequestErrorMock,
 }));
 
+describe('mapGithubError', () => {
+  it.each([400, 409, 422])('maps HTTP %i to a terminal provider rejection', async (status) => {
+    const error = new RequestErrorMock(`GitHub rejected request with HTTP ${status}`, status);
+
+    const result = mapGithubError(() => Promise.reject(error));
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'provider-rejected',
+      message: `GitHub rejected request with HTTP ${status}`,
+      status,
+    });
+  });
+
+  it('preserves the status when mapping provider unavailability', async () => {
+    const error = new RequestErrorMock('GitHub is unavailable', 503);
+
+    const result = mapGithubError(() => Promise.reject(error));
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'provider-unavailable',
+      message: 'GitHub is unavailable',
+      status: 503,
+    });
+  });
+});
+
 describe('OctokitGithubApiClient.createInstallationAccessToken', () => {
   beforeEach(() => {
     createInstallationAccessTokenMock.mockReset();

package/src/api/client.ts

@@ -433,13 +433,19 @@ export async function mapGithubError<T>(
     if (error instanceof GithubIntegrationProviderError) throw error;
     if (error instanceof RequestError) {
       if (error.status === 404) {
-        throw new GithubIntegrationProviderError(notFoundReason, error.message);
+        throw new GithubIntegrationProviderError(
+          notFoundReason,
+          error.message,
+          undefined,
+          error.status,
+        );
       }
       if (error.status === 429 || isGithubRateLimitError(error)) {
         throw new GithubIntegrationProviderError(
           'rate-limited',
           error.message,
           retryAfterSeconds(error),
+          error.status,
         );
       }
       if (error.status === 401 || error.status === 403) {
@@ -447,10 +453,24 @@ export async function mapGithubError<T>(
           'access-denied',
           error.message,
           retryAfterSeconds(error),
+          error.status,
         );
       }
       if (error.status >= 500) {
-        throw new GithubIntegrationProviderError('provider-unavailable', error.message);
+        throw new GithubIntegrationProviderError(
+          'provider-unavailable',
+          error.message,
+          undefined,
+          error.status,
+        );
+      }
+      if (error.status >= 400) {
+        throw new GithubIntegrationProviderError(
+          'provider-rejected',
+          error.message,
+          undefined,
+          error.status,
+        );
       }
     }
     if (error instanceof Error && error.name === 'AbortError') {

package/src/api/installation-token-envelope.ts

@@ -19,15 +19,21 @@ const providerErrorReasons = [
   'rate-limited',
   'timeout',
   'provider-unavailable',
+  'provider-rejected',
   'malformed-provider-response',
   'content-too-large',
   'too-many-files',
 ] as const satisfies readonly IntegrationProviderErrorReason[];
 
 const providerErrorReasonSchema = z.enum(providerErrorReasons);
+const backoffErrorSchema = z.object({
+  message: z.string(),
+  status: z.number().int().optional(),
+});
 const terminalMintErrorReasons = new Set<IntegrationProviderErrorReason>([
   'access-denied',
   'installation-not-found',
+  'provider-rejected',
   'malformed-provider-response',
 ]);
 
@@ -44,6 +50,7 @@ const installationTokenEnvelopeSchema = z.object({
   permissions: z.record(z.string(), z.enum(['read', 'write', 'admin'])).optional(),
   backoffUntil: z.string().datetime().optional(),
   backoffReason: providerErrorReasonSchema.optional(),
+  backoffError: backoffErrorSchema.optional(),
 });
 
 export interface InstallationTokenEnvelope {
@@ -52,6 +59,12 @@ export interface InstallationTokenEnvelope {
   permissions?: Record<string, 'read' | 'write' | 'admin'> | undefined;
   backoffUntil?: Date | undefined;
   backoffReason?: IntegrationProviderErrorReason | undefined;
+  backoffError?:
+    | {
+        message: string;
+        status?: number | undefined;
+      }
+    | undefined;
 }
 
 export type MintErrorClass = 'transient' | 'terminal';
@@ -75,6 +88,7 @@ export function encodeInstallationTokenEnvelope(envelope: InstallationTokenEnvel
       backoffUntil: envelope.backoffUntil.toISOString(),
     }),
     ...(envelope.backoffReason !== undefined && {backoffReason: envelope.backoffReason}),
+    ...(envelope.backoffError !== undefined && {backoffError: envelope.backoffError}),
   });
 }
 
@@ -95,6 +109,7 @@ export function parseInstallationTokenEnvelope(raw: string): InstallationTokenEn
     permissions: result.data.permissions,
     backoffUntil: result.data.backoffUntil ? new Date(result.data.backoffUntil) : undefined,
     backoffReason: result.data.backoffReason,
+    backoffError: result.data.backoffError,
   };
 }
 
@@ -151,18 +166,25 @@ export function backoffMs(classified: ClassifiedMintError): number {
 export function providerErrorFromBackoff(
   reason: IntegrationProviderErrorReason,
   retryAfterMs: number,
+  backoffError?: InstallationTokenEnvelope['backoffError'],
 ): GithubIntegrationProviderError {
   return new GithubIntegrationProviderError(
     reason,
-    `GitHub installation token mint is backed off after ${reason}`,
+    backoffError?.message ?? `GitHub installation token mint is backed off after ${reason}`,
     Math.max(1, Math.ceil(retryAfterMs / 1000)),
+    backoffError?.status,
   );
 }
 
 export function toProviderError(error: unknown): GithubIntegrationProviderError {
   if (error instanceof GithubIntegrationProviderError) return error;
   if (error instanceof IntegrationProviderError) {
-    return new GithubIntegrationProviderError(error.reason, error.message, error.retryAfterSeconds);
+    return new GithubIntegrationProviderError(
+      error.reason,
+      error.message,
+      error.retryAfterSeconds,
+      error.status,
+    );
   }
   return new GithubIntegrationProviderError(
     'provider-unavailable',

package/src/api/shared-installation-token-cache.test.ts

@@ -190,6 +190,34 @@ describe('SharedInstallationTokenCache', () => {
     expect(mint).toHaveBeenCalledTimes(1);
   });
 
+  it('preserves terminal provider rejection details through backoff', async () => {
+    const store = createStore();
+    const mint = vi
+      .fn()
+      .mockRejectedValue(
+        new GithubIntegrationProviderError(
+          'provider-rejected',
+          'commit_id is missing',
+          undefined,
+          422,
+        ),
+      );
+    const shared = cache({store});
+
+    await expect(shared.getOrMint(installationId, mint)).rejects.toMatchObject({
+      reason: 'provider-rejected',
+      message: 'commit_id is missing',
+      status: 422,
+    });
+    await expect(shared.getOrMint(installationId, mint)).rejects.toMatchObject({
+      reason: 'provider-rejected',
+      message: 'commit_id is missing',
+      status: 422,
+    });
+
+    expect(mint).toHaveBeenCalledTimes(1);
+  });
+
   it('serves stale when refresh minting fails while the token is still valid', async () => {
     const store = createStore();
     setEnvelope(store, token('ghs_existing', '2026-06-10T11:04:30.000Z'));

package/src/api/shared-installation-token-cache.ts

@@ -113,6 +113,7 @@ export class SharedInstallationTokenCache implements InstallationTokenCache {
       throw providerErrorFromBackoff(
         envelope?.backoffReason ?? 'provider-unavailable',
         (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime(),
+        envelope?.backoffError,
       );
     }
 
@@ -131,6 +132,10 @@ export class SharedInstallationTokenCache implements InstallationTokenCache {
         permissions: envelope?.permissions,
         backoffUntil: until,
         backoffReason: classified.reason,
+        backoffError: {
+          message: providerError.message,
+          ...(providerError.status === undefined ? {} : {status: providerError.status}),
+        },
       }).catch((writeError) => {
         logger().warn(
           {installationId: params.installationId, reason: classified.reason, error: writeError},
@@ -215,6 +220,7 @@ export class SharedInstallationTokenCache implements InstallationTokenCache {
       throw providerErrorFromBackoff(
         params.envelope.backoffReason,
         params.envelope.backoffUntil.getTime() - initialNow.getTime(),
+        params.envelope.backoffError,
       );
     }
 
@@ -231,6 +237,7 @@ export class SharedInstallationTokenCache implements InstallationTokenCache {
         throw providerErrorFromBackoff(
           envelope?.backoffReason ?? 'provider-unavailable',
           (envelope?.backoffUntil?.getTime() ?? now.getTime()) - now.getTime(),
+          envelope?.backoffError,
         );
       }
     }