@shipfox/api-integration-core 2.0.0

package/src/core/agent-tool-selection.ts

@@ -0,0 +1,80 @@
+import type {
+  AgentToolCatalogEntry,
+  AgentToolSelectionCatalog,
+  IntegrationCapability,
+  IntegrationProviderKind,
+} from '@shipfox/api-integration-core-dto';
+import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
+import {listIntegrationConnections} from '#db/connections.js';
+
+export type AgentToolSelectionCatalogs = ReadonlyMap<
+  IntegrationProviderKind,
+  AgentToolSelectionCatalog
+>;
+export type AgentToolCatalogs = ReadonlyMap<
+  IntegrationProviderKind,
+  readonly AgentToolCatalogEntry[]
+>;
+
+export interface WorkspaceConnectionSnapshotEntry {
+  readonly id: string;
+  readonly provider: IntegrationProviderKind;
+  readonly capabilities: readonly IntegrationCapability[];
+}
+
+export type WorkspaceConnectionSnapshot = ReadonlyMap<string, WorkspaceConnectionSnapshotEntry>;
+export type LoadWorkspaceConnectionSnapshot = (
+  workspaceId: string,
+) => Promise<WorkspaceConnectionSnapshot>;
+
+export async function buildAgentToolSelectionCatalogs(
+  registry: IntegrationProviderRegistry,
+): Promise<AgentToolSelectionCatalogs> {
+  const entries = await Promise.all(
+    registry.list('agent_tools').map(async (provider) => {
+      const adapter = provider.adapters.agent_tools;
+      if (adapter === undefined) {
+        throw new Error(`Integration provider "${provider.provider}" has no agent tools adapter`);
+      }
+      return [provider.provider, await adapter.selectionCatalog()] as const;
+    }),
+  );
+  return new Map(entries);
+}
+
+export async function buildAgentToolCatalogs(
+  registry: IntegrationProviderRegistry,
+): Promise<AgentToolCatalogs> {
+  const entries = await Promise.all(
+    registry.list('agent_tools').map(async (provider) => {
+      const adapter = provider.adapters.agent_tools;
+      if (adapter === undefined) {
+        throw new Error(`Integration provider "${provider.provider}" has no agent tools adapter`);
+      }
+      return [provider.provider, await adapter.catalog()] as const;
+    }),
+  );
+  return new Map(entries);
+}
+
+export function createWorkspaceConnectionSnapshotLoader(
+  registry: IntegrationProviderRegistry,
+): LoadWorkspaceConnectionSnapshot {
+  const capabilitiesByProvider = new Map(
+    registry.list().map((provider) => [provider.provider, provider.capabilities]),
+  );
+
+  return async (workspaceId) => {
+    const connections = await listIntegrationConnections({workspaceId});
+    return new Map(
+      connections.map((connection) => [
+        connection.slug,
+        {
+          id: connection.id,
+          provider: connection.provider,
+          capabilities: capabilitiesByProvider.get(connection.provider) ?? [],
+        },
+      ]),
+    );
+  };
+}

package/src/core/entities/connection.ts

@@ -0,0 +1,4 @@
+export type {
+  IntegrationConnection,
+  IntegrationConnectionLifecycleStatus,
+} from '@shipfox/api-integration-core-dto';

package/src/core/entities/provider.ts

@@ -0,0 +1,21 @@
+import type {
+  IntegrationProvider as CoreIntegrationProvider,
+  RegisteredIntegrationProvider as CoreRegisteredIntegrationProvider,
+} from '@shipfox/api-integration-core-dto';
+import type {RouteExport} from '@shipfox/node-fastify';
+
+export type {
+  AgentToolCallInput,
+  AgentToolCatalogEntry,
+  AgentToolJsonSchema,
+  AgentToolSensitivity,
+  AgentToolSession,
+  AgentToolsProvider,
+  IntegrationCapability,
+  IntegrationProviderAdapters,
+  IntegrationProviderKind,
+  OpenAgentToolsSessionInput,
+} from '@shipfox/api-integration-core-dto';
+
+export type IntegrationProvider = CoreIntegrationProvider<string, RouteExport>;
+export type RegisteredIntegrationProvider = CoreRegisteredIntegrationProvider<string, RouteExport>;

package/src/core/errors.ts

@@ -0,0 +1,55 @@
+import {
+  ConnectionSlugConflictError,
+  IntegrationProviderError,
+  type IntegrationProviderErrorReason,
+} from '@shipfox/api-integration-core-dto';
+import type {IntegrationCapability, IntegrationProviderKind} from '#core/entities/provider.js';
+
+export class IntegrationConnectionNotFoundError extends Error {
+  constructor(connectionId: string) {
+    super(`Integration connection not found: ${connectionId}`);
+  }
+}
+
+export class IntegrationConnectionInactiveError extends Error {
+  constructor(connectionId: string) {
+    super(`Integration connection is not active: ${connectionId}`);
+  }
+}
+
+export class IntegrationConnectionWorkspaceMismatchError extends Error {
+  constructor(connectionId: string) {
+    super(`Integration connection does not belong to the requested workspace: ${connectionId}`);
+  }
+}
+
+export class IntegrationConnectionAlreadyExistsError extends Error {
+  constructor(
+    public readonly workspaceId: string,
+    public readonly provider: IntegrationProviderKind,
+    public readonly externalAccountId: string,
+  ) {
+    super(`Integration connection already exists: ${workspaceId}/${provider}/${externalAccountId}`);
+    this.name = 'IntegrationConnectionAlreadyExistsError';
+  }
+}
+
+export class IntegrationCapabilityUnavailableError extends Error {
+  constructor(capability: IntegrationCapability, provider: IntegrationProviderKind) {
+    super(`Integration provider ${provider} does not expose ${capability}`);
+  }
+}
+
+export class IntegrationCheckoutUnsupportedError extends Error {
+  constructor(public readonly provider: IntegrationProviderKind) {
+    super(`Integration provider ${provider} cannot create a checkout spec`);
+  }
+}
+
+export class IntegrationProviderUnavailableError extends Error {
+  constructor(provider: IntegrationProviderKind) {
+    super(`No integration provider registered for ${provider}`);
+  }
+}
+
+export {ConnectionSlugConflictError, IntegrationProviderError, type IntegrationProviderErrorReason};

package/src/core/providers/agent-tools.ts

@@ -0,0 +1,10 @@
+export type {
+  AgentToolCallInput,
+  AgentToolCatalogEntry,
+  AgentToolCatalogMethod,
+  AgentToolJsonSchema,
+  AgentToolSensitivity,
+  AgentToolSession,
+  AgentToolsProvider,
+  OpenAgentToolsSessionInput,
+} from '@shipfox/api-integration-core-dto';

package/src/core/providers/redact-checkout-spec.test.ts

@@ -0,0 +1,78 @@
+import type {CheckoutSpec} from '@shipfox/api-integration-core-dto';
+import {redactCheckoutSpec} from './redact-checkout-spec.js';
+
+describe('redactCheckoutSpec', () => {
+  it('masks the credential token while keeping the other fields intact', () => {
+    const expiresAt = new Date('2026-06-10T12:00:00.000Z');
+    const spec: CheckoutSpec = {
+      repositoryUrl: 'https://github.com/shipfox/platform.git',
+      ref: 'main',
+      credentials: {username: 'x-access-token', token: 'ghs_supersecret', expiresAt},
+    };
+
+    const redacted = redactCheckoutSpec(spec);
+
+    expect(redacted).toEqual({
+      repositoryUrl: 'https://github.com/shipfox/platform.git',
+      ref: 'main',
+      credentials: {username: 'x-access-token', token: '***', expiresAt},
+    });
+  });
+
+  it('does not mutate the original spec', () => {
+    const spec: CheckoutSpec = {
+      repositoryUrl: 'https://github.com/shipfox/platform.git',
+      ref: 'main',
+      credentials: {
+        username: 'x-access-token',
+        token: 'ghs_supersecret',
+        expiresAt: new Date('2026-06-10T12:00:00.000Z'),
+      },
+    };
+
+    redactCheckoutSpec(spec);
+
+    expect(spec.credentials?.token).toBe('ghs_supersecret');
+  });
+
+  it('returns the spec unchanged when there are no credentials and the url is clean', () => {
+    const spec: CheckoutSpec = {
+      repositoryUrl: 'https://gitea.local/gitea-owner/platform.git',
+      ref: 'main',
+    };
+
+    const redacted = redactCheckoutSpec(spec);
+
+    expect(redacted).toBe(spec);
+  });
+
+  it('strips credentials embedded in repositoryUrl as a defense in depth', () => {
+    const spec: CheckoutSpec = {
+      repositoryUrl: 'https://x-access-token:ghs_supersecret@github.com/shipfox/platform.git',
+      ref: 'main',
+      credentials: {
+        username: 'x-access-token',
+        token: 'ghs_supersecret',
+        expiresAt: new Date('2026-06-10T12:00:00.000Z'),
+      },
+    };
+
+    const redacted = redactCheckoutSpec(spec);
+
+    expect(redacted.repositoryUrl).toBe('https://github.com/shipfox/platform.git');
+    expect(redacted.repositoryUrl).not.toContain('ghs_supersecret');
+    expect(redacted.credentials?.token).toBe('***');
+  });
+
+  it('strips embedded credentials even when the spec has no credentials field', () => {
+    const spec: CheckoutSpec = {
+      repositoryUrl: 'https://x-access-token:ghs_supersecret@github.com/shipfox/platform.git',
+      ref: 'main',
+    };
+
+    const redacted = redactCheckoutSpec(spec);
+
+    expect(redacted.repositoryUrl).toBe('https://github.com/shipfox/platform.git');
+    expect(redacted.repositoryUrl).not.toContain('ghs_supersecret');
+  });
+});

package/src/core/providers/redact-checkout-spec.ts

@@ -0,0 +1,20 @@
+import type {CheckoutSpec} from '@shipfox/api-integration-core-dto';
+import {REDACTION_PLACEHOLDER, stripUrlCredentials} from '@shipfox/redact';
+
+/**
+ * Returns a copy of `spec` that is safe to log: the credential token is masked
+ * and any userinfo a provider mistakenly left in `repositoryUrl` is stripped.
+ * Returns the original spec unchanged when it has no credentials and the URL is
+ * already clean.
+ */
+export function redactCheckoutSpec(spec: CheckoutSpec): CheckoutSpec {
+  const repositoryUrl = stripUrlCredentials(spec.repositoryUrl);
+  if (!spec.credentials) {
+    return repositoryUrl === spec.repositoryUrl ? spec : {...spec, repositoryUrl};
+  }
+  return {
+    ...spec,
+    repositoryUrl,
+    credentials: {...spec.credentials, token: REDACTION_PLACEHOLDER},
+  };
+}

package/src/core/providers/registry.test.ts

@@ -0,0 +1,138 @@
+import {
+  IntegrationCapabilityUnavailableError,
+  IntegrationProviderUnavailableError,
+} from '#core/errors.js';
+import {createIntegrationProviderRegistry} from './registry.js';
+
+function sourceControlAdapter() {
+  return {
+    listRepositories: async () => {
+      await Promise.resolve();
+      return {repositories: [], nextCursor: null};
+    },
+    resolveRepository: async () => {
+      await Promise.resolve();
+      throw new Error('not used');
+    },
+    listFiles: async () => {
+      await Promise.resolve();
+      return {files: [], nextCursor: null};
+    },
+    fetchFile: async () => {
+      await Promise.resolve();
+      throw new Error('not used');
+    },
+  };
+}
+
+function agentToolsAdapter() {
+  return {
+    catalog: () => [],
+    selectionCatalog: () => ({selectors: []}),
+    openSession: async () => {
+      await Promise.resolve();
+      return {
+        call: async () => {
+          await Promise.resolve();
+          return {};
+        },
+      };
+    },
+  };
+}
+
+describe('integration provider registry', () => {
+  it('lists providers by capability', () => {
+    const registry = createIntegrationProviderRegistry([
+      {
+        provider: 'gitea',
+        displayName: 'Gitea',
+        adapters: {
+          source_control: sourceControlAdapter(),
+        },
+      },
+      {
+        provider: 'github',
+        displayName: 'GitHub',
+      },
+    ]);
+
+    const result = registry.list('source_control');
+
+    expect(result.map((provider) => provider.provider)).toEqual(['gitea']);
+  });
+
+  it('computes the agent tools capability from the adapter', () => {
+    const registry = createIntegrationProviderRegistry([
+      {
+        provider: 'github',
+        displayName: 'GitHub',
+        adapters: {
+          agent_tools: agentToolsAdapter(),
+        },
+      },
+    ]);
+
+    const result = registry.list('agent_tools');
+
+    expect(result.map((provider) => provider.provider)).toEqual(['github']);
+    expect(registry.get('github').capabilities).toEqual(['agent_tools']);
+  });
+
+  it('keeps provider sets isolated per registry instance', () => {
+    const emptyRegistry = createIntegrationProviderRegistry([]);
+    const giteaRegistry = createIntegrationProviderRegistry([
+      {
+        provider: 'gitea',
+        displayName: 'Gitea',
+        adapters: {
+          source_control: sourceControlAdapter(),
+        },
+      },
+    ]);
+
+    expect(giteaRegistry.get('gitea').provider).toBe('gitea');
+    expect(() => emptyRegistry.get('gitea')).toThrow(IntegrationProviderUnavailableError);
+  });
+
+  it('rejects source-control access for providers without the capability implementation', () => {
+    const registry = createIntegrationProviderRegistry([
+      {
+        provider: 'gitea',
+        displayName: 'Gitea',
+      },
+    ]);
+
+    const result = () => registry.getSourceControl('gitea');
+
+    expect(result).toThrow(IntegrationCapabilityUnavailableError);
+  });
+
+  it('rejects duplicate provider registrations', () => {
+    const result = () =>
+      createIntegrationProviderRegistry([
+        {
+          provider: 'gitea',
+          displayName: 'Gitea',
+        },
+        {
+          provider: 'gitea',
+          displayName: 'Gitea Duplicate',
+        },
+      ]);
+
+    expect(result).toThrow('Duplicate integration provider registered');
+  });
+
+  it('rejects invalid provider ids', () => {
+    const result = () =>
+      createIntegrationProviderRegistry([
+        {
+          provider: 'GitHub',
+          displayName: 'GitHub',
+        },
+      ]);
+
+    expect(result).toThrow('Invalid integration provider id');
+  });
+});

package/src/core/providers/registry.ts

@@ -0,0 +1,90 @@
+import {isLowercaseAlphaSlug} from '@shipfox/regex';
+import type {
+  IntegrationCapability,
+  IntegrationProvider,
+  IntegrationProviderAdapters,
+  IntegrationProviderKind,
+  RegisteredIntegrationProvider,
+} from '#core/entities/provider.js';
+import {
+  IntegrationCapabilityUnavailableError,
+  IntegrationProviderUnavailableError,
+} from '#core/errors.js';
+
+export interface IntegrationProviderRegistry {
+  list(capability?: IntegrationCapability | undefined): RegisteredIntegrationProvider[];
+  get(provider: IntegrationProviderKind): RegisteredIntegrationProvider;
+  getAdapter<Capability extends IntegrationCapability>(
+    provider: IntegrationProviderKind,
+    capability: Capability,
+  ): NonNullable<IntegrationProviderAdapters[Capability]>;
+  getSourceControl(
+    provider: IntegrationProviderKind,
+  ): NonNullable<IntegrationProviderAdapters['source_control']>;
+}
+
+export function createIntegrationProviderRegistry(
+  providers: IntegrationProvider[],
+): IntegrationProviderRegistry {
+  return new MapIntegrationProviderRegistry(providers);
+}
+
+class MapIntegrationProviderRegistry implements IntegrationProviderRegistry {
+  private readonly providers: Map<IntegrationProviderKind, RegisteredIntegrationProvider>;
+
+  constructor(providers: IntegrationProvider[]) {
+    this.providers = new Map();
+
+    for (const provider of providers) {
+      if (!isLowercaseAlphaSlug(provider.provider)) {
+        throw new Error(`Invalid integration provider id: ${provider.provider}`);
+      }
+      if (this.providers.has(provider.provider)) {
+        throw new Error(`Duplicate integration provider registered: ${provider.provider}`);
+      }
+
+      this.providers.set(provider.provider, normalizeProvider(provider));
+    }
+  }
+
+  list(capability?: IntegrationCapability | undefined): RegisteredIntegrationProvider[] {
+    const providers = [...this.providers.values()];
+    if (!capability) return providers;
+    return providers.filter((provider) => provider.capabilities.includes(capability));
+  }
+
+  get(provider: IntegrationProviderKind): RegisteredIntegrationProvider {
+    const resolved = this.providers.get(provider);
+    if (!resolved) throw new IntegrationProviderUnavailableError(provider);
+    return resolved;
+  }
+
+  getAdapter<Capability extends IntegrationCapability>(
+    provider: IntegrationProviderKind,
+    capability: Capability,
+  ): NonNullable<IntegrationProviderAdapters[Capability]> {
+    const resolved = this.get(provider);
+    const adapter = resolved.adapters[capability];
+    if (!adapter) {
+      throw new IntegrationCapabilityUnavailableError(capability, provider);
+    }
+    return adapter as NonNullable<IntegrationProviderAdapters[Capability]>;
+  }
+
+  getSourceControl(
+    provider: IntegrationProviderKind,
+  ): NonNullable<IntegrationProviderAdapters['source_control']> {
+    return this.getAdapter(provider, 'source_control');
+  }
+}
+
+function normalizeProvider(provider: IntegrationProvider): RegisteredIntegrationProvider {
+  const adapters = provider.adapters ?? {};
+  return {
+    ...provider,
+    adapters,
+    capabilities: Object.entries(adapters)
+      .filter(([, adapter]) => Boolean(adapter))
+      .map(([capability]) => capability as IntegrationCapability),
+  };
+}

package/src/core/providers/source-control.ts

@@ -0,0 +1,17 @@
+export type {
+  CheckoutCredentials,
+  CheckoutPermissions,
+  CheckoutSpec,
+  CreateCheckoutSpecInput,
+  FetchFileInput,
+  FileEntry,
+  FilePage,
+  FileSnapshot,
+  ListFilesInput,
+  ListRepositoriesInput,
+  RepositoryPage,
+  RepositorySnapshot,
+  RepositoryVisibility,
+  ResolveRepositoryInput,
+  SourceControlProvider,
+} from '@shipfox/api-integration-core-dto';