@shipfox/api-integration-spi 1.1.0 → 2.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-spi",
   "license": "MIT",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -18,7 +18,7 @@
     }
   },
   "dependencies": {
-    "@shipfox/api-integration-core-dto": "12.2.0"
+    "@shipfox/api-integration-core-dto": "14.0.0"
   },
   "imports": {
     "#*": "./dist/*"

package/src/contracts.test.ts

@@ -3,6 +3,7 @@ import {
   IntegrationProviderError,
   isValidGitObjectId,
   isValidGitRefName,
+  isValidResolvableRef,
   isValidTriggerRef,
   parseProviderRepositoryId,
 } from './contracts.js';
@@ -29,6 +30,9 @@ describe('git ref names', () => {
     'refs/heads/.foo',
     'refs/heads/foo.',
     'refs/heads/foo@{bar',
+    'a'.repeat(40),
+    'b'.repeat(64),
+    '0'.repeat(40),
   ])('rejects %s', (ref) => {
     expect(isValidGitRefName(ref)).toBe(false);
   });
@@ -38,6 +42,26 @@ describe('git ref names', () => {
   });
 });
 
+describe('resolvable refs', () => {
+  it.each([
+    'refs/heads/main',
+    'refs/heads/feature/review',
+    'refs/tags/v1.0.0',
+  ])('accepts %s', (ref) => {
+    expect(isValidResolvableRef(ref)).toBe(true);
+  });
+
+  it.each(['refs/pull/17/head'])('rejects %s', (ref) => {
+    expect(isValidResolvableRef(ref)).toBe(false);
+  });
+
+  it('rejects every name a trigger ref rejects', () => {
+    for (const ref of ['', 'HEAD', '-main', 'refs/heads/foo bar', 'refs/heads/foo..bar']) {
+      expect(isValidResolvableRef(ref)).toBe(false);
+    }
+  });
+});
+
 describe('git object ids', () => {
   it.each(['a'.repeat(40), 'b'.repeat(64)])('accepts a full object id', (value) => {
     expect(isValidGitObjectId(value)).toBe(true);

package/src/contracts.ts

@@ -53,6 +53,16 @@ export interface ResolveRepositoryInput<
   externalRepositoryId: string;
 }
 
+export interface ResolveRefInput<Connection extends IntegrationConnection = IntegrationConnection>
+  extends ResolveRepositoryInput<Connection> {
+  ref: string;
+}
+
+export interface ResolvedRef {
+  ref: string;
+  commit: string;
+}
+
 export interface FileSnapshot {
   path: string;
   ref: string;
@@ -129,6 +139,11 @@ export interface SourceControlProvider<
   listFiles(input: ListFilesInput<Connection>): Promise<FilePage>;
   fetchFile(input: FetchFileInput<Connection>): Promise<FileSnapshot>;
   resolveTriggerReference(payload: unknown): TriggerReference | null;
+  /**
+   * Pins a branch or tag name to the commit it currently points at.
+   * The snapshot can become unreachable before a caller uses it.
+   */
+  resolveRef(input: ResolveRefInput<Connection>): Promise<ResolvedRef>;
   createCheckoutSpec?(input: CreateCheckoutSpecInput<Connection>): Promise<CheckoutSpec>;
 }
 
@@ -223,6 +238,13 @@ export interface IntegrationProvider<
 > {
   provider: ProviderKind;
   displayName: string;
+  /**
+   * The event names this provider documents for its handler.
+   * Provider-minted names are never treated as a closed set by validation; the
+   * catalog is a curated diagnostic aid and may omit provider events. Providers
+   * without a documented catalog, including built-in trigger sources, omit it.
+   */
+  eventCatalog?: import('@shipfox/api-integration-core-dto').IntegrationEventCatalog | undefined;
   adapters?: IntegrationProviderAdapters<Connection> | undefined;
   routes?: Route[] | undefined;
   connectionExternalUrl?(connection: Connection): Promise<string | undefined>;
@@ -249,10 +271,13 @@ export type IntegrationProviderErrorReason =
   | 'repository-not-found'
   | 'installation-not-found'
   | 'file-not-found'
+  | 'ref-not-found'
+  | 'ref-invalid'
   | 'access-denied'
   | 'rate-limited'
   | 'timeout'
   | 'provider-unavailable'
+  | 'provider-rejected'
   | 'malformed-provider-response'
   | 'content-too-large'
   | 'too-many-files';
@@ -262,6 +287,7 @@ export class IntegrationProviderError extends Error {
     public readonly reason: IntegrationProviderErrorReason,
     message: string,
     public readonly retryAfterSeconds?: number | undefined,
+    public readonly status?: number | undefined,
   ) {
     super(message);
     this.name = 'IntegrationProviderError';
@@ -363,6 +389,18 @@ export function isValidTriggerRef(ref: string): boolean {
   return isValidGitRefName(ref);
 }
 
+/**
+ * Validates a ref the platform may resolve to a commit: any safe git ref name
+ * except pull-request refs. Raw object ids do not satisfy the safe git ref
+ * name rules because valid refs must contain a slash. `refs/pull/N/head` can
+ * point at a fork and providers serve any commit in the repository network by
+ * SHA, so accepting names only keeps resolutions on refs a member pushed to
+ * the project repository.
+ */
+export function isValidResolvableRef(ref: string): boolean {
+  return isValidTriggerRef(ref) && !ref.startsWith('refs/pull/');
+}
+
 export function isValidGitObjectId(value: string): boolean {
   return GIT_OBJECT_ID_PATTERN.test(value) && !ZERO_GIT_OBJECT_ID_PATTERN.test(value);
 }