@shipfox/api-integration-spi 0.2.2 → 1.0.1

package/package.json

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

package/src/contracts.test.ts

@@ -1,9 +1,58 @@
 import {
   buildProviderRepositoryId,
   IntegrationProviderError,
+  isValidGitObjectId,
+  isValidGitRefName,
+  isValidTriggerRef,
   parseProviderRepositoryId,
 } from './contracts.js';
 
+describe('git ref names', () => {
+  it.each([
+    'refs/heads/main',
+    'refs/heads/feature/review',
+    'refs/heads/foo./bar',
+    'refs/heads/foo/-bar',
+    'refs/pull/17/head',
+  ])('accepts %s', (ref) => {
+    expect(isValidGitRefName(ref)).toBe(true);
+  });
+
+  it.each([
+    '',
+    'HEAD',
+    'main',
+    '-main',
+    'refs/heads/foo bar',
+    'refs/heads/foo..bar',
+    'refs/heads/foo.lock',
+    'refs/heads/.foo',
+    'refs/heads/foo.',
+    'refs/heads/foo@{bar',
+  ])('rejects %s', (ref) => {
+    expect(isValidGitRefName(ref)).toBe(false);
+  });
+
+  it.each(['refs/tags/-evil', 'refs/heads/feature/-evil'])('accepts safe trigger ref %s', (ref) => {
+    expect(isValidTriggerRef(ref)).toBe(true);
+  });
+});
+
+describe('git object ids', () => {
+  it.each(['a'.repeat(40), 'b'.repeat(64)])('accepts a full object id', (value) => {
+    expect(isValidGitObjectId(value)).toBe(true);
+  });
+
+  it.each([
+    'a',
+    'abcdef1234567890',
+    '0'.repeat(40),
+    'g'.repeat(40),
+  ])('rejects an invalid object id', (value) => {
+    expect(isValidGitObjectId(value)).toBe(false);
+  });
+});
+
 describe('provider repository identifiers', () => {
   it('prefixes provider-owned identifiers', () => {
     const result = buildProviderRepositoryId('github', '42');

package/src/contracts.ts

@@ -2,6 +2,9 @@ export type IntegrationProviderKind = string;
 export type IntegrationCapability = 'source_control' | 'agent_tools';
 export type IntegrationConnectionLifecycleStatus = 'active' | 'disabled' | 'error';
 
+const GIT_OBJECT_ID_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+const ZERO_GIT_OBJECT_ID_PATTERN = /^0+$/;
+
 export interface IntegrationConnection<
   ProviderKind extends IntegrationProviderKind = IntegrationProviderKind,
 > {
@@ -110,6 +113,14 @@ export interface CreateCheckoutSpecInput<
   permissions?: CheckoutPermissions | undefined;
 }
 
+export interface TriggerReference {
+  externalRepositoryId: string;
+  ref: string;
+  commit: string;
+  /** Provider handle of whoever caused the event, when the payload names one. */
+  actor: string | null;
+}
+
 export interface SourceControlProvider<
   Connection extends IntegrationConnection = IntegrationConnection,
 > {
@@ -117,6 +128,7 @@ export interface SourceControlProvider<
   resolveRepository(input: ResolveRepositoryInput<Connection>): Promise<RepositorySnapshot>;
   listFiles(input: ListFilesInput<Connection>): Promise<FilePage>;
   fetchFile(input: FetchFileInput<Connection>): Promise<FileSnapshot>;
+  resolveTriggerReference(payload: unknown): TriggerReference | null;
   createCheckoutSpec?(input: CreateCheckoutSpecInput<Connection>): Promise<CheckoutSpec>;
 }
 
@@ -293,3 +305,58 @@ export function parseProviderRepositoryId(
   }
   return value;
 }
+
+/** Checks the constraints enforced by `git check-ref-format`. */
+export function isValidGitRefName(ref: string): boolean {
+  if (!ref || ref === '@' || ref.startsWith('-')) return false;
+  if (
+    !ref.includes('/') ||
+    ref.startsWith('/') ||
+    ref.endsWith('/') ||
+    ref.includes('//') ||
+    ref.includes('..') ||
+    ref.includes('@{') ||
+    ref.endsWith('.')
+  ) {
+    return false;
+  }
+  if (
+    [...ref].some((character) => {
+      const code = character.codePointAt(0) ?? 0;
+      return code <= 0x20 || code === 0x7f || '~^:?*[]\\'.includes(character);
+    })
+  ) {
+    return false;
+  }
+
+  const components = ref.split('/');
+  return components.every(
+    (component) =>
+      component.length > 0 && !component.startsWith('.') && !component.endsWith('.lock'),
+  );
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | null {
+  return isRecord(value) ? value : null;
+}
+
+export function nonEmptyString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+export function positiveInteger(value: unknown): number | null {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : null;
+}
+
+/** Validates a provider ref before it is passed to a git operation. */
+export function isValidTriggerRef(ref: string): boolean {
+  return isValidGitRefName(ref);
+}
+
+export function isValidGitObjectId(value: string): boolean {
+  return GIT_OBJECT_ID_PATTERN.test(value) && !ZERO_GIT_OBJECT_ID_PATTERN.test(value);
+}

package/src/ports.ts

@@ -1,6 +1,7 @@
 import type {
   IntegrationEventReceivedEvent,
   SourcePushPayload,
+  SourceRepositoryIdentity,
 } from '@shipfox/api-integration-core-dto';
 import type {IntegrationConnection, IntegrationConnectionLifecycleStatus} from '#contracts.js';
 
@@ -37,6 +38,20 @@ export type PublishSourcePushFn = (params: {
   push: SourcePushPayload;
 }) => Promise<{published: boolean}>;
 
+export type PublishSourceRepositoryUpdatedFn = (params: {
+  tx: IntegrationTx;
+  provider: string;
+  source: string;
+  workspaceId: string;
+  connectionId: string;
+  connectionName: string;
+  deliveryId: string;
+  receivedAt: string;
+  rawPayload: unknown;
+  event: string;
+  repositories: SourceRepositoryIdentity[];
+}) => Promise<{published: boolean}>;
+
 export type RecordDeliveryOnlyFn = (params: {
   tx: IntegrationTx;
   provider: string;