@shipfox/api-integration-core-dto 2.0.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@shipfox/api-integration-core-dto",
+  "license": "MIT",
+  "version": "2.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/integration/core-dto"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/depcruise": "1.0.1",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/ts-config": "1.3.8"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "depcruise": "shipfox-depcruise",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/contracts/index.ts

@@ -0,0 +1,43 @@
+export type {
+  AgentToolCallInput,
+  AgentToolCatalogEntry,
+  AgentToolCatalogMethod,
+  AgentToolJsonSchema,
+  AgentToolSelectionCatalog,
+  AgentToolSelector,
+  AgentToolSelectorKind,
+  AgentToolSensitivity,
+  AgentToolSession,
+  AgentToolsProvider,
+  CheckoutCredentials,
+  CheckoutPermissions,
+  CheckoutSpec,
+  CreateCheckoutSpecInput,
+  FetchFileInput,
+  FileEntry,
+  FilePage,
+  FileSnapshot,
+  IntegrationCapability,
+  IntegrationConnection,
+  IntegrationConnectionLifecycleStatus,
+  IntegrationProvider,
+  IntegrationProviderAdapters,
+  IntegrationProviderErrorReason,
+  IntegrationProviderKind,
+  ListFilesInput,
+  ListRepositoriesInput,
+  OpenAgentToolsSessionInput,
+  RegisteredIntegrationProvider,
+  RepositoryPage,
+  RepositorySnapshot,
+  RepositoryVisibility,
+  ResolveRepositoryInput,
+  SourceControlProvider,
+} from './integrations.js';
+export {
+  buildProviderRepositoryId,
+  IntegrationProviderError,
+  MAX_REPOSITORY_FILE_BYTES,
+  parseProviderRepositoryId,
+  toIntegrationConnectionDto,
+} from './integrations.js';

package/src/contracts/integrations.test.ts

@@ -0,0 +1,64 @@
+import {
+  buildProviderRepositoryId,
+  IntegrationProviderError,
+  parseProviderRepositoryId,
+} from './integrations.js';
+
+const MISSING_PREFIX = /missing a provider prefix/;
+const WRONG_PROVIDER = /not owned by provider github/;
+const MISSING_VALUE = /missing a provider-owned value/;
+
+describe('buildProviderRepositoryId', () => {
+  it('joins the provider and value with a colon', () => {
+    const result = buildProviderRepositoryId('github', '42');
+
+    expect(result).toBe('github:42');
+  });
+});
+
+describe('parseProviderRepositoryId', () => {
+  it('returns the provider-owned value for a well-formed id', () => {
+    const result = parseProviderRepositoryId('github:42', 'github');
+
+    expect(result).toBe('42');
+  });
+
+  it('keeps colons inside the value (splits only on the first separator)', () => {
+    const result = parseProviderRepositoryId('github:org/repo:extra', 'github');
+
+    expect(result).toBe('org/repo:extra');
+  });
+
+  it.each([
+    ['42', 'no provider prefix'],
+    [':42', 'an empty provider prefix'],
+  ])('rejects %s (%s)', (externalRepositoryId) => {
+    const parse = () => parseProviderRepositoryId(externalRepositoryId, 'github');
+
+    expect(parse).toThrow(IntegrationProviderError);
+    expect(parse).toThrow(MISSING_PREFIX);
+  });
+
+  it('rejects an id owned by a different provider', () => {
+    const parse = () => parseProviderRepositoryId('gitlab:42', 'github');
+
+    expect(parse).toThrow(IntegrationProviderError);
+    expect(parse).toThrow(WRONG_PROVIDER);
+  });
+
+  it('rejects an id with a prefix but no value', () => {
+    const parse = () => parseProviderRepositoryId('github:', 'github');
+
+    expect(parse).toThrow(IntegrationProviderError);
+    expect(parse).toThrow(MISSING_VALUE);
+  });
+
+  it('surfaces the repository-not-found reason on the thrown error', () => {
+    expect.assertions(1);
+    try {
+      parseProviderRepositoryId('42', 'github');
+    } catch (error) {
+      expect((error as IntegrationProviderError).reason).toBe('repository-not-found');
+    }
+  });
+});

package/src/contracts/integrations.ts

@@ -0,0 +1,312 @@
+export type IntegrationProviderKind = string;
+export type IntegrationCapability = 'source_control' | 'agent_tools';
+export type IntegrationConnectionLifecycleStatus = 'active' | 'disabled' | 'error';
+
+export interface IntegrationConnection<
+  ProviderKind extends IntegrationProviderKind = IntegrationProviderKind,
+> {
+  id: string;
+  workspaceId: string;
+  provider: ProviderKind;
+  externalAccountId: string;
+  slug: string;
+  displayName: string;
+  lifecycleStatus: IntegrationConnectionLifecycleStatus;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export type RepositoryVisibility = 'public' | 'private' | 'internal' | 'unknown';
+
+export interface RepositorySnapshot {
+  externalRepositoryId: string;
+  owner: string;
+  name: string;
+  fullName: string;
+  defaultBranch: string;
+  visibility: RepositoryVisibility;
+  cloneUrl: string;
+  htmlUrl: string;
+}
+
+export interface RepositoryPage {
+  repositories: RepositorySnapshot[];
+  nextCursor: string | null;
+}
+
+export interface ListRepositoriesInput<
+  Connection extends IntegrationConnection = IntegrationConnection,
+> {
+  connection: Connection;
+  limit: number;
+  cursor?: string | undefined;
+  search?: string | undefined;
+}
+
+export interface ResolveRepositoryInput<
+  Connection extends IntegrationConnection = IntegrationConnection,
+> {
+  connection: Connection;
+  externalRepositoryId: string;
+}
+
+export interface FileSnapshot {
+  path: string;
+  ref: string;
+  content: string;
+}
+
+export interface FileEntry {
+  path: string;
+  type: 'file';
+  size: number | null;
+}
+
+export interface FilePage {
+  files: FileEntry[];
+  nextCursor: string | null;
+}
+
+export interface ListFilesInput<Connection extends IntegrationConnection = IntegrationConnection>
+  extends ResolveRepositoryInput<Connection> {
+  ref: string;
+  prefix: string;
+  limit: number;
+  cursor?: string | undefined;
+}
+
+export interface FetchFileInput<Connection extends IntegrationConnection = IntegrationConnection>
+  extends ResolveRepositoryInput<Connection> {
+  ref: string;
+  path: string;
+}
+
+export interface CheckoutCredentials {
+  username: string;
+  token: string;
+  expiresAt: Date;
+}
+
+export interface CheckoutGitAuthor {
+  name: string;
+  email: string;
+}
+
+export interface CheckoutPermissions {
+  contents: 'read' | 'write';
+}
+
+export interface CheckoutSpec {
+  /**
+   * Clone URL that must never embed authentication material. Credentials live
+   * only in `credentials` so a redaction helper can mask them; a provider that
+   * embeds a token in this URL would bypass redaction and leak it into logs,
+   * `git remote -v`, and persisted job rows.
+   */
+  repositoryUrl: string;
+  ref: string;
+  credentials?: CheckoutCredentials | undefined;
+  gitAuthor?: CheckoutGitAuthor | undefined;
+}
+
+export interface CreateCheckoutSpecInput<
+  Connection extends IntegrationConnection = IntegrationConnection,
+> extends ResolveRepositoryInput<Connection> {
+  ref?: string | undefined;
+  permissions?: CheckoutPermissions | undefined;
+}
+
+export interface SourceControlProvider<
+  Connection extends IntegrationConnection = IntegrationConnection,
+> {
+  listRepositories(input: ListRepositoriesInput<Connection>): Promise<RepositoryPage>;
+  resolveRepository(input: ResolveRepositoryInput<Connection>): Promise<RepositorySnapshot>;
+  listFiles(input: ListFilesInput<Connection>): Promise<FilePage>;
+  fetchFile(input: FetchFileInput<Connection>): Promise<FileSnapshot>;
+  createCheckoutSpec?(input: CreateCheckoutSpecInput<Connection>): Promise<CheckoutSpec>;
+}
+
+export type AgentToolSensitivity = 'read' | 'write';
+export type AgentToolJsonSchema = Record<string, unknown>;
+
+export interface AgentToolCatalogMethod<RequiredScope = unknown> {
+  id: string;
+  description: string;
+  sensitivity: AgentToolSensitivity;
+  sensitive: boolean;
+  requiredScope: RequiredScope;
+}
+
+export interface AgentToolCatalogEntry<RequiredScope = unknown> {
+  id: string;
+  description: string;
+  sensitivity: AgentToolSensitivity;
+  sensitive: boolean;
+  requiredScope: RequiredScope;
+  inputSchema: AgentToolJsonSchema;
+  outputSchema?: AgentToolJsonSchema | undefined;
+  methods?: readonly AgentToolCatalogMethod<RequiredScope>[] | undefined;
+}
+
+export type AgentToolSelectorKind = 'family' | 'family_wildcard' | 'method' | 'standalone';
+
+export interface AgentToolSelector {
+  readonly token: string;
+  readonly kind: AgentToolSelectorKind;
+  readonly sensitivity: AgentToolSensitivity;
+  readonly sensitive: boolean;
+}
+
+export interface AgentToolSelectionCatalog {
+  readonly selectors: readonly AgentToolSelector[];
+}
+
+export interface AgentToolCallInput {
+  toolId: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface AgentToolSession<CallResult = unknown> {
+  call(input: AgentToolCallInput): Promise<CallResult>;
+  close?(): Promise<void>;
+}
+
+export interface OpenAgentToolsSessionInput<
+  Connection extends IntegrationConnection = IntegrationConnection,
+  RequiredScope = unknown,
+  ProviderScope = unknown,
+> {
+  connection: Connection;
+  tools: readonly AgentToolCatalogEntry<RequiredScope>[];
+  scope: ProviderScope;
+}
+
+export interface AgentToolsProvider<
+  Connection extends IntegrationConnection = IntegrationConnection,
+  RequiredScope = unknown,
+  ProviderScope = unknown,
+  CallResult = unknown,
+> {
+  catalog():
+    | readonly AgentToolCatalogEntry<RequiredScope>[]
+    | Promise<readonly AgentToolCatalogEntry<RequiredScope>[]>;
+  selectionCatalog(): AgentToolSelectionCatalog | Promise<AgentToolSelectionCatalog>;
+  openSession(
+    input: OpenAgentToolsSessionInput<Connection, RequiredScope, ProviderScope>,
+  ): Promise<AgentToolSession<CallResult>>;
+}
+
+export interface IntegrationProviderAdapters<
+  Connection extends IntegrationConnection = IntegrationConnection,
+> {
+  source_control?: SourceControlProvider<Connection> | undefined;
+  agent_tools?: AgentToolsProvider<Connection> | undefined;
+}
+
+export interface IntegrationProvider<
+  ProviderKind extends IntegrationProviderKind = IntegrationProviderKind,
+  Route = unknown,
+  Connection extends IntegrationConnection<ProviderKind> = IntegrationConnection<ProviderKind>,
+> {
+  provider: ProviderKind;
+  displayName: string;
+  adapters?: IntegrationProviderAdapters<Connection> | undefined;
+  routes?: Route[] | undefined;
+  /**
+   * Resolves the provider-side home of a connection (e.g. the Sentry org or the
+   * GitHub installation settings page). Returns undefined when the connection has
+   * no external home or the provider-side record is missing.
+   */
+  connectionExternalUrl?(connection: Connection): Promise<string | undefined>;
+}
+
+export interface RegisteredIntegrationProvider<
+  ProviderKind extends IntegrationProviderKind = IntegrationProviderKind,
+  Route = unknown,
+  Connection extends IntegrationConnection<ProviderKind> = IntegrationConnection<ProviderKind>,
+> extends IntegrationProvider<ProviderKind, Route, Connection> {
+  adapters: IntegrationProviderAdapters<Connection>;
+  capabilities: IntegrationCapability[];
+}
+
+export type IntegrationProviderErrorReason =
+  | 'repository-not-found'
+  | 'installation-not-found'
+  | 'file-not-found'
+  | 'access-denied'
+  | 'rate-limited'
+  | 'timeout'
+  | 'provider-unavailable'
+  | 'malformed-provider-response'
+  | 'content-too-large'
+  | 'too-many-files';
+
+export class IntegrationProviderError extends Error {
+  constructor(
+    public readonly reason: IntegrationProviderErrorReason,
+    message: string,
+    public readonly retryAfterSeconds?: number | undefined,
+  ) {
+    super(message);
+    this.name = 'IntegrationProviderError';
+  }
+}
+
+export const MAX_REPOSITORY_FILE_BYTES = 1_000_000;
+
+export function toIntegrationConnectionDto(
+  connection: IntegrationConnection,
+  options: {
+    capabilities: IntegrationCapability[];
+    externalUrl?: string | undefined;
+  },
+) {
+  return {
+    id: connection.id,
+    workspace_id: connection.workspaceId,
+    provider: connection.provider,
+    external_account_id: connection.externalAccountId,
+    slug: connection.slug,
+    display_name: connection.displayName,
+    lifecycle_status: connection.lifecycleStatus,
+    capabilities: options.capabilities,
+    ...(options.externalUrl ? {external_url: options.externalUrl} : {}),
+    created_at: connection.createdAt.toISOString(),
+    updated_at: connection.updatedAt.toISOString(),
+  };
+}
+
+export function buildProviderRepositoryId(
+  provider: IntegrationProviderKind,
+  value: string,
+): string {
+  return `${provider}:${value}`;
+}
+
+export function parseProviderRepositoryId(
+  externalRepositoryId: string,
+  expectedProvider: IntegrationProviderKind,
+): string {
+  const separatorIndex = externalRepositoryId.indexOf(':');
+  if (separatorIndex <= 0) {
+    throw new IntegrationProviderError(
+      'repository-not-found',
+      `External repository id is missing a provider prefix: ${externalRepositoryId}`,
+    );
+  }
+  const prefix = externalRepositoryId.slice(0, separatorIndex);
+  const value = externalRepositoryId.slice(separatorIndex + 1);
+  if (prefix !== expectedProvider) {
+    throw new IntegrationProviderError(
+      'repository-not-found',
+      `External repository id ${externalRepositoryId} is not owned by provider ${expectedProvider}`,
+    );
+  }
+  if (!value) {
+    throw new IntegrationProviderError(
+      'repository-not-found',
+      `External repository id ${externalRepositoryId} is missing a provider-owned value`,
+    );
+  }
+  return value;
+}

package/src/errors.ts

@@ -0,0 +1,6 @@
+export class ConnectionSlugConflictError extends Error {
+  constructor(cause: unknown) {
+    super('Could not allocate a unique integration connection slug. Try again.', {cause});
+    this.name = 'ConnectionSlugConflictError';
+  }
+}

package/src/events.test.ts

@@ -0,0 +1,109 @@
+import {
+  INTEGRATION_EVENT_RECEIVED,
+  INTEGRATION_SOURCE_COMMIT_PUSHED,
+  integrationEventReceivedSchema,
+  integrationSourceCommitPushedSchema,
+  integrationsEventSchemas,
+} from './events.js';
+
+const validEventReceived = {
+  provider: 'github',
+  source: 'github',
+  event: 'push',
+  workspaceId: 'ws-1',
+  connectionId: 'conn-1',
+  connectionName: 'Acme Production',
+  deliveryId: 'delivery-1',
+  receivedAt: '2026-06-21T00:00:00.000Z',
+  payload: {opaque: true},
+};
+
+const validCommitPushed = {
+  provider: 'github',
+  workspaceId: 'ws-1',
+  connectionId: 'conn-1',
+  deliveryId: 'delivery-1',
+  receivedAt: '2026-06-21T00:00:00.000Z',
+  push: {
+    externalRepositoryId: 'acme/repo',
+    ref: 'refs/heads/main',
+    headCommitSha: 'abc123',
+    defaultBranch: 'main',
+    isDefaultBranch: true,
+  },
+};
+
+describe('integrationSourceCommitPushedSchema', () => {
+  it('parses a valid commit-pushed payload unchanged', () => {
+    const result = integrationSourceCommitPushedSchema.parse(validCommitPushed);
+
+    expect(result).toEqual(validCommitPushed);
+  });
+
+  it('rejects a payload missing a top-level field', () => {
+    const {provider: _provider, ...withoutProvider} = validCommitPushed;
+
+    const parse = () => integrationSourceCommitPushedSchema.parse(withoutProvider);
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects a payload missing a nested push field', () => {
+    const {headCommitSha: _headCommitSha, ...pushWithoutSha} = validCommitPushed.push;
+    const input = {...validCommitPushed, push: pushWithoutSha};
+
+    const parse = () => integrationSourceCommitPushedSchema.parse(input);
+
+    expect(parse).toThrow();
+  });
+
+  it('strips unknown keys (tolerant of forward-compatible producer additions)', () => {
+    const input = {...validCommitPushed, addedLater: 'ignored'};
+
+    const result = integrationSourceCommitPushedSchema.parse(input);
+
+    expect(result).toEqual(validCommitPushed);
+  });
+});
+
+describe('integrationEventReceivedSchema', () => {
+  it('parses a valid generic integration event envelope unchanged', () => {
+    const result = integrationEventReceivedSchema.parse(validEventReceived);
+
+    expect(result).toEqual(validEventReceived);
+  });
+
+  it('defaults missing connection names to null for queued events', () => {
+    const {connectionName: _connectionName, ...withoutConnectionName} = validEventReceived;
+
+    const result = integrationEventReceivedSchema.parse(withoutConnectionName);
+
+    expect(result).toEqual({...withoutConnectionName, connectionName: null});
+  });
+
+  it('rejects a payload missing the opaque provider payload key', () => {
+    const {payload: _payload, ...withoutPayload} = validEventReceived;
+
+    const parse = () => integrationEventReceivedSchema.parse(withoutPayload);
+
+    expect(parse).toThrow();
+  });
+
+  it('strips unknown envelope keys', () => {
+    const input = {...validEventReceived, addedLater: 'ignored'};
+
+    const result = integrationEventReceivedSchema.parse(input);
+
+    expect(result).toEqual(validEventReceived);
+  });
+});
+
+describe('integrationsEventSchemas', () => {
+  it('registers every integration publisher event type', () => {
+    const registeredTypes = Object.keys(integrationsEventSchemas).sort();
+
+    expect(registeredTypes).toEqual(
+      [INTEGRATION_EVENT_RECEIVED, INTEGRATION_SOURCE_COMMIT_PUSHED].sort(),
+    );
+  });
+});

package/src/events.ts

@@ -0,0 +1,91 @@
+import {z} from 'zod';
+
+export const INTEGRATION_EVENT_RECEIVED = 'integrations.event.received' as const;
+
+const nonEmptyStringSchema = z.string().nonempty();
+const isoDateTimeSchema = z.string().datetime();
+const requiredUnknownSchema = z.custom<unknown>((value) => value !== undefined);
+const nullableConnectionNameSchema = nonEmptyStringSchema.nullish().default(null);
+
+export const integrationEventReceivedSchema = z.object({
+  provider: nonEmptyStringSchema,
+  source: nonEmptyStringSchema,
+  event: nonEmptyStringSchema,
+  workspaceId: nonEmptyStringSchema,
+  connectionId: nonEmptyStringSchema,
+  // Denormalized so trigger consumers can render the connection name without a
+  // synchronous callback into the integrations module.
+  connectionName: nullableConnectionNameSchema,
+  deliveryId: nonEmptyStringSchema,
+  receivedAt: isoDateTimeSchema,
+  payload: requiredUnknownSchema,
+});
+export type IntegrationEventReceivedEvent = z.infer<typeof integrationEventReceivedSchema>;
+
+// A source-control push, normalized by the producing provider and carried by
+// `INTEGRATION_SOURCE_COMMIT_PUSHED` for domain consumers.
+export const sourcePushSchema = z.object({
+  externalRepositoryId: nonEmptyStringSchema,
+  ref: nonEmptyStringSchema,
+  headCommitSha: nonEmptyStringSchema,
+  defaultBranch: nonEmptyStringSchema,
+  isDefaultBranch: z.boolean(),
+});
+export type SourcePushPayload = z.infer<typeof sourcePushSchema>;
+
+export const INTEGRATION_SOURCE_COMMIT_PUSHED =
+  'integrations.source_control.commit_pushed' as const;
+
+// Typed, provider-agnostic source-control event. The producing provider owns the
+// translation from its raw webhook into this shape, so domain consumers never decode
+// provider payloads. `isDefaultBranch` is a fact; the branch policy lives in the consumer.
+export const integrationSourceCommitPushedSchema = z.object({
+  provider: nonEmptyStringSchema,
+  workspaceId: nonEmptyStringSchema,
+  connectionId: nonEmptyStringSchema,
+  deliveryId: nonEmptyStringSchema,
+  receivedAt: isoDateTimeSchema,
+  push: sourcePushSchema,
+});
+export type IntegrationSourceCommitPushedEvent = z.infer<
+  typeof integrationSourceCommitPushedSchema
+>;
+
+export interface SentryIssuePayload {
+  action: SentryIssueAction;
+  issueId: string;
+  shortId: string | null;
+  title: string;
+  culprit: string | null;
+  level: string | null;
+  status: string | null;
+  platform: string | null;
+  webUrl: string | null;
+  issueUrl: string | null;
+  projectUrl: string | null;
+  firstSeenAt: string | null;
+  lastSeenAt: string | null;
+}
+
+// Single source of truth for Sentry issue actions: the sentry-dto webhook schema
+// builds its z.enum from this tuple, so accepted webhook actions and the published
+// SentryIssuePayload contract cannot drift.
+export const SENTRY_ISSUE_ACTIONS = [
+  'created',
+  'resolved',
+  'assigned',
+  'archived',
+  'unresolved',
+] as const;
+
+export type SentryIssueAction = (typeof SENTRY_ISSUE_ACTIONS)[number];
+
+export interface IntegrationsEventMap {
+  [INTEGRATION_EVENT_RECEIVED]: IntegrationEventReceivedEvent;
+  [INTEGRATION_SOURCE_COMMIT_PUSHED]: IntegrationSourceCommitPushedEvent;
+}
+
+export const integrationsEventSchemas = {
+  [INTEGRATION_EVENT_RECEIVED]: integrationEventReceivedSchema,
+  [INTEGRATION_SOURCE_COMMIT_PUSHED]: integrationSourceCommitPushedSchema,
+} satisfies Record<keyof IntegrationsEventMap, z.ZodType>;

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from '#contracts/index.js';
+export * from '#errors.js';
+export * from '#events.js';
+export * from '#ports.js';
+export * from '#schemas/index.js';
+export * from '#slug.js';