@shipfox/client-integrations 0.2.0

package/src/components/integration-gallery.tsx

@@ -0,0 +1,49 @@
+import type {IntegrationCapabilityDto} from '@shipfox/api-integration-core-dto';
+import {useActiveWorkspace} from '@shipfox/client-auth';
+import {IntegrationGalleryForWorkspace} from './integration-gallery-for-workspace.js';
+
+export interface IntegrationGalleryProps {
+  capability?: IntegrationCapabilityDto;
+  emptyProvidersMessage?: string;
+  workspaceId?: string;
+}
+
+export function IntegrationGallery({
+  capability,
+  emptyProvidersMessage = 'Enable at least one provider in the application settings.',
+  workspaceId,
+}: IntegrationGalleryProps) {
+  if (workspaceId) {
+    return (
+      <IntegrationGalleryForWorkspace
+        workspaceId={workspaceId}
+        capability={capability}
+        emptyProvidersMessage={emptyProvidersMessage}
+      />
+    );
+  }
+
+  return (
+    <RoutedIntegrationGallery
+      capability={capability}
+      emptyProvidersMessage={emptyProvidersMessage}
+    />
+  );
+}
+
+function RoutedIntegrationGallery({
+  capability,
+  emptyProvidersMessage,
+}: {
+  capability: IntegrationCapabilityDto | undefined;
+  emptyProvidersMessage: string;
+}) {
+  const workspace = useActiveWorkspace();
+  return (
+    <IntegrationGalleryForWorkspace
+      workspaceId={workspace.id}
+      capability={capability}
+      emptyProvidersMessage={emptyProvidersMessage}
+    />
+  );
+}

package/src/components/integration-usage-events.test.ts

@@ -0,0 +1,80 @@
+import type {IntegrationConnectionDto} from '@shipfox/api-integration-core-dto';
+import {linearWebhookEventNames} from '@shipfox/api-integration-linear-dto';
+import {WEBHOOK_RECEIVED_EVENT} from '@shipfox/api-integration-webhook-dto';
+import {usageEventsForConnection} from './integration-usage-events.js';
+
+const baseConnection = {
+  id: '44444444-4444-4444-8444-444444444444',
+  workspace_id: '11111111-1111-4111-8111-111111111111',
+  provider: 'github',
+  external_account_id: 'installation-1',
+  slug: 'github_acme_corp',
+  display_name: 'acme-corp',
+  lifecycle_status: 'active',
+  capabilities: [],
+  created_at: '2026-03-12T00:00:00.000Z',
+  updated_at: '2026-03-12T00:00:00.000Z',
+} satisfies IntegrationConnectionDto;
+
+describe('usageEventsForConnection', () => {
+  it('lists the GitHub webhook events used by workflow triggers', () => {
+    const connection = {
+      ...baseConnection,
+      provider: 'github',
+      capabilities: ['source_control'],
+    } satisfies IntegrationConnectionDto;
+
+    const events = usageEventsForConnection(connection);
+    const values = events.map((event) => event.value);
+
+    expect(values[0]).toBe('push');
+    expect(values).toEqual(expect.arrayContaining(['pull_request', 'workflow_run']));
+    expect(events.find((event) => event.value === 'workflow_run')?.label).toBe('workflow_run');
+  });
+
+  it('uses the webhook received event for webhook connections', () => {
+    const connection = {
+      ...baseConnection,
+      provider: 'webhook',
+      slug: 'stripe-prod',
+    } satisfies IntegrationConnectionDto;
+
+    const events = usageEventsForConnection(connection);
+
+    expect(events).toEqual([{value: WEBHOOK_RECEIVED_EVENT, label: WEBHOOK_RECEIVED_EVENT}]);
+  });
+
+  it('uses source-control push for uncataloged source-control providers', () => {
+    const connection = {
+      ...baseConnection,
+      provider: 'gitea',
+      capabilities: ['source_control'],
+    } satisfies IntegrationConnectionDto;
+
+    const events = usageEventsForConnection(connection);
+
+    expect(events).toEqual([{value: 'push', label: 'push'}]);
+  });
+
+  it('uses Linear webhook names directly', () => {
+    const connection = {
+      ...baseConnection,
+      provider: 'linear',
+    } satisfies IntegrationConnectionDto;
+
+    const events = usageEventsForConnection(connection);
+
+    expect(events.map((event) => event.value)).toEqual(linearWebhookEventNames);
+  });
+
+  it('falls back to a generic received event for uncataloged providers', () => {
+    const connection = {
+      ...baseConnection,
+      provider: 'mystery',
+    } satisfies IntegrationConnectionDto;
+
+    const events = usageEventsForConnection(connection);
+
+    expect(events).toEqual([{value: 'received', label: 'received'}]);
+  });
+});

package/src/components/integration-usage-events.ts

@@ -0,0 +1,116 @@
+import type {IntegrationConnectionDto, SentryIssueAction} from '@shipfox/api-integration-core-dto';
+import {SENTRY_ISSUE_ACTIONS} from '@shipfox/api-integration-core-dto';
+import {linearWebhookEventNames} from '@shipfox/api-integration-linear-dto';
+import {WEBHOOK_RECEIVED_EVENT} from '@shipfox/api-integration-webhook-dto';
+import type {IntegrationUsageEvent} from './integration-usage-modal.js';
+
+const GITHUB_EVENTS = [
+  'push',
+  'branch_protection_configuration',
+  'branch_protection_rule',
+  'check_run',
+  'check_suite',
+  'code_scanning_alert',
+  'commit_comment',
+  'create',
+  'custom_property',
+  'custom_property_values',
+  'delete',
+  'dependabot_alert',
+  'deploy_key',
+  'deployment',
+  'deployment_protection_rule',
+  'deployment_review',
+  'deployment_status',
+  'discussion',
+  'discussion_comment',
+  'fork',
+  'github_app_authorization',
+  'gollum',
+  'installation',
+  'installation_repositories',
+  'installation_target',
+  'issue_comment',
+  'issue_dependencies',
+  'issues',
+  'label',
+  'marketplace_purchase',
+  'member',
+  'membership',
+  'merge_group',
+  'meta',
+  'milestone',
+  'org_block',
+  'organization',
+  'package',
+  'page_build',
+  'personal_access_token_request',
+  'ping',
+  'project',
+  'project_card',
+  'project_column',
+  'projects_v2',
+  'projects_v2_item',
+  'projects_v2_status_update',
+  'public',
+  'pull_request',
+  'pull_request_review',
+  'pull_request_review_comment',
+  'pull_request_review_thread',
+  'registry_package',
+  'release',
+  'repository',
+  'repository_advisory',
+  'repository_dispatch',
+  'repository_import',
+  'repository_ruleset',
+  'repository_vulnerability_alert',
+  'secret_scanning_alert',
+  'secret_scanning_alert_location',
+  'secret_scanning_scan',
+  'security_advisory',
+  'security_and_analysis',
+  'sponsorship',
+  'star',
+  'status',
+  'sub_issues',
+  'team',
+  'team_add',
+  'watch',
+  'workflow_dispatch',
+  'workflow_job',
+  'workflow_run',
+] as const;
+
+export function usageEventsForConnection(
+  connection: IntegrationConnectionDto,
+): IntegrationUsageEvent[] {
+  if (connection.provider === 'webhook') {
+    return [{value: WEBHOOK_RECEIVED_EVENT, label: WEBHOOK_RECEIVED_EVENT}];
+  }
+
+  if (connection.provider === 'github') {
+    return GITHUB_EVENTS.map((event) => ({value: event, label: event}));
+  }
+
+  if (connection.provider === 'sentry') {
+    return SENTRY_ISSUE_ACTIONS.map((action) => ({
+      value: `issue.${action}`,
+      label: sentryIssueEventLabel(action),
+    }));
+  }
+
+  if (connection.provider === 'linear') {
+    return linearWebhookEventNames.map((event) => ({value: event, label: event}));
+  }
+
+  if (connection.capabilities.includes('source_control')) {
+    return [{value: 'push', label: 'push'}];
+  }
+
+  return [{value: 'received', label: 'received'}];
+}
+
+function sentryIssueEventLabel(action: SentryIssueAction): string {
+  return `issue.${action}`;
+}

package/src/components/integration-usage-modal.tsx

@@ -0,0 +1,178 @@
+import type {IntegrationConnectionDto} from '@shipfox/api-integration-core-dto';
+import {Button} from '@shipfox/react-ui/button';
+import {
+  CodeBlock,
+  CodeBlockBody,
+  CodeBlockContent,
+  CodeBlockCopyButton,
+  CodeBlockFilename,
+  CodeBlockFiles,
+  CodeBlockHeader,
+  CodeBlockItem,
+} from '@shipfox/react-ui/code-block';
+import {
+  Modal,
+  ModalBody,
+  ModalContent,
+  ModalFooter,
+  ModalHeader,
+  ModalTitle,
+} from '@shipfox/react-ui/modal';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@shipfox/react-ui/select';
+import {Text} from '@shipfox/react-ui/typography';
+import type {ReactNode} from 'react';
+import {useEffect, useMemo, useState} from 'react';
+import {ConnectionStatusBadge} from '#connection-status-badge.js';
+
+export interface IntegrationUsageEvent {
+  value: string;
+  label: string;
+}
+
+interface IntegrationUsageModalProps {
+  connection: IntegrationConnectionDto | null;
+  events: IntegrationUsageEvent[];
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  children?: ReactNode;
+}
+
+const WORKFLOW_FILENAME = '.shipfox/workflows/integration.yml';
+
+export function IntegrationUsageModal({
+  connection,
+  events,
+  open,
+  onOpenChange,
+  children,
+}: IntegrationUsageModalProps) {
+  const [selectedEvent, setSelectedEvent] = useState('');
+  const eventValuesKey = events.map((event) => event.value).join('\u0000');
+
+  useEffect(() => {
+    const eventValues = eventValuesKey ? eventValuesKey.split('\u0000') : [];
+    setSelectedEvent((current) =>
+      eventValues.includes(current) ? current : (eventValues[0] ?? ''),
+    );
+  }, [eventValuesKey]);
+
+  const workflowExample = connection
+    ? buildWorkflowExample({source: connection.slug, event: selectedEvent})
+    : '';
+  const data = useMemo(
+    () => [{language: 'yaml', filename: WORKFLOW_FILENAME, code: workflowExample}],
+    [workflowExample],
+  );
+  const title = connection ? `Use ${connection.display_name}` : 'Use integration';
+
+  return (
+    <Modal open={open && connection !== null} onOpenChange={onOpenChange}>
+      <ModalContent aria-describedby={undefined} className="max-h-[calc(100vh-32px)] max-w-[640px]">
+        <ModalTitle className="sr-only">{title}</ModalTitle>
+        <ModalHeader>
+          <div className="flex min-w-0 flex-col gap-2">
+            <div className="flex min-w-0 items-center gap-8">
+              <Text size="lg" aria-hidden="true" className="truncate">
+                {title}
+              </Text>
+              {connection ? (
+                <ConnectionStatusBadge status={connection.lifecycle_status} className="shrink-0" />
+              ) : null}
+            </div>
+            <Text size="sm" className="text-foreground-neutral-muted">
+              Reference this connection from a workflow trigger.
+            </Text>
+          </div>
+        </ModalHeader>
+        {connection ? (
+          <>
+            <ModalBody className="min-h-0 flex-1 gap-24 overflow-y-auto overflow-x-clip scrollbar">
+              <section className="flex w-full flex-col gap-12">
+                <Text size="md" bold>
+                  Usage
+                </Text>
+                {events.length > 1 ? (
+                  <div className="flex flex-col gap-6">
+                    <label
+                      htmlFor="integration-usage-event"
+                      className="font-display text-sm font-medium text-foreground-neutral-base"
+                    >
+                      Event
+                    </label>
+                    <Select value={selectedEvent} onValueChange={setSelectedEvent}>
+                      <SelectTrigger id="integration-usage-event">
+                        <SelectValue placeholder="Select event" />
+                      </SelectTrigger>
+                      <SelectContent>
+                        {events.map((event) => (
+                          <SelectItem key={event.value} value={event.value}>
+                            {event.label}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                  </div>
+                ) : null}
+                <CodeBlock data={data} className="h-auto min-h-0 rounded-8">
+                  <CodeBlockHeader>
+                    <CodeBlockFiles>
+                      {(item) => (
+                        <CodeBlockFilename value={item.filename}>{item.filename}</CodeBlockFilename>
+                      )}
+                    </CodeBlockFiles>
+                    <CodeBlockCopyButton />
+                  </CodeBlockHeader>
+                  <CodeBlockBody>
+                    {(item) => (
+                      <CodeBlockItem value={item.filename}>
+                        <CodeBlockContent
+                          language="yaml"
+                          syntaxHighlighting
+                          highlightedLineRange={{startLine: 3, endLine: 4}}
+                        >
+                          {item.code}
+                        </CodeBlockContent>
+                      </CodeBlockItem>
+                    )}
+                  </CodeBlockBody>
+                </CodeBlock>
+              </section>
+              {children ? (
+                <section className="flex w-full flex-col gap-12">
+                  <Text size="md" bold>
+                    Details
+                  </Text>
+                  {children}
+                </section>
+              ) : null}
+            </ModalBody>
+            <ModalFooter>
+              <Button type="button" onClick={() => onOpenChange(false)}>
+                Done
+              </Button>
+            </ModalFooter>
+          </>
+        ) : null}
+      </ModalContent>
+    </Modal>
+  );
+}
+
+function buildWorkflowExample({source, event}: {source: string; event: string}) {
+  return [
+    'triggers:',
+    '  integration:',
+    `    source: ${source}`,
+    `    event: ${event}`,
+    'jobs:',
+    '  handle-event:',
+    '    steps:',
+    '      - run: echo "Received event"',
+  ].join('\n');
+}

package/src/components/provider-grid.tsx

@@ -0,0 +1,163 @@
+import type {
+  IntegrationProviderDto,
+  ListIntegrationProvidersResponseDto,
+} from '@shipfox/api-integration-core-dto';
+import {QueryLoadError} from '@shipfox/client-ui';
+import {Card} from '@shipfox/react-ui/card';
+import {EmptyState} from '@shipfox/react-ui/empty-state';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Skeleton} from '@shipfox/react-ui/skeleton';
+import {Text} from '@shipfox/react-ui/typography';
+import {cn} from '@shipfox/react-ui/utils';
+import type {UseQueryResult} from '@tanstack/react-query';
+import {Link} from '@tanstack/react-router';
+import {IntegrationIcon} from '#integration-icon.js';
+import {PROVIDER_CATALOG} from '#provider-catalog.js';
+
+export interface ProviderGridProps {
+  providersQuery: UseQueryResult<ListIntegrationProvidersResponseDto, Error>;
+  workspaceId: string;
+  emptyMessage: string;
+  loadingLabel?: string;
+  errorSubject?: string;
+  onOpenProvider?: ((provider: string) => void) | undefined;
+}
+
+export const PROVIDER_GRID_CLASS = 'grid grid-cols-2 gap-12 max-[760px]:grid-cols-1';
+
+export const PROVIDER_SURFACE_CLASS =
+  'overflow-hidden rounded-8 border border-border-neutral-base bg-background-neutral-base';
+
+export function ProviderGrid({
+  providersQuery,
+  workspaceId,
+  emptyMessage,
+  loadingLabel = 'Loading providers',
+  errorSubject = 'available integrations',
+  onOpenProvider,
+}: ProviderGridProps) {
+  const providers = providersQuery.data?.providers ?? [];
+  const installableProviders = providers.filter((provider) => PROVIDER_CATALOG[provider.provider]);
+
+  if (providersQuery.isPending) return <ProviderGridSkeleton label={loadingLabel} />;
+
+  if (providersQuery.isError && providersQuery.data === undefined) {
+    return (
+      <div className={cn(PROVIDER_SURFACE_CLASS, 'px-16')}>
+        <QueryLoadError query={providersQuery} subject={errorSubject} />
+      </div>
+    );
+  }
+
+  if (providersQuery.data !== undefined && installableProviders.length === 0) {
+    return (
+      <div className={cn(PROVIDER_SURFACE_CLASS, 'px-16')}>
+        <EmptyState
+          icon="componentLine"
+          title="No integrations available"
+          description={emptyMessage}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <ul className={PROVIDER_GRID_CLASS}>
+      {installableProviders.map((provider) => (
+        <li key={provider.provider}>
+          <ProviderCard
+            provider={provider}
+            workspaceId={workspaceId}
+            onOpenProvider={onOpenProvider}
+          />
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function ProviderCard({
+  provider,
+  workspaceId,
+  onOpenProvider,
+}: {
+  provider: IntegrationProviderDto;
+  workspaceId: string;
+  onOpenProvider?: ((provider: string) => void) | undefined;
+}) {
+  const catalog = PROVIDER_CATALOG[provider.provider];
+  if (!catalog) return null;
+
+  if (catalog.kind === 'modal-connect') {
+    return (
+      <button
+        type="button"
+        aria-label={`Add ${provider.display_name}`}
+        onClick={() => onOpenProvider?.(provider.provider)}
+        className="group flex h-full w-full min-w-0 items-center justify-between gap-12 rounded-8 border border-border-neutral-base bg-background-neutral-base p-16 text-left transition-colors hover:bg-background-components-hover focus-visible:shadow-button-neutral-focus focus-visible:outline-none"
+      >
+        <ProviderCardContent provider={provider} action="Add" />
+      </button>
+    );
+  }
+
+  return (
+    <Link
+      to={catalog.setupPath}
+      params={{wid: workspaceId}}
+      aria-label={`Install ${provider.display_name}`}
+      className="group flex h-full min-w-0 items-center justify-between gap-12 rounded-8 border border-border-neutral-base bg-background-neutral-base p-16 transition-colors hover:bg-background-components-hover focus-visible:shadow-button-neutral-focus focus-visible:outline-none"
+    >
+      <ProviderCardContent provider={provider} action="Install" />
+    </Link>
+  );
+}
+
+function ProviderCardContent({
+  provider,
+  action,
+}: {
+  provider: IntegrationProviderDto;
+  action: 'Add' | 'Install';
+}) {
+  return (
+    <>
+      <span className="flex min-w-0 items-center gap-12">
+        <IntegrationIcon
+          source={provider.provider}
+          aria-hidden
+          className="size-24 shrink-0 text-foreground-neutral-base"
+        />
+        <Text as="span" size="md" bold className="truncate">
+          {provider.display_name}
+        </Text>
+      </span>
+      <span className="flex shrink-0 items-center gap-4 text-foreground-neutral-muted transition-colors group-hover:text-foreground-highlight-interactive">
+        <Text as="span" size="sm">
+          {action}
+        </Text>
+        <Icon name="chevronRight" className="size-16" />
+      </span>
+    </>
+  );
+}
+
+function ProviderGridSkeleton({label}: {label: string}) {
+  return (
+    <ul role="status" aria-label={label} className={PROVIDER_GRID_CLASS}>
+      {[0, 1, 2, 3].map((tile) => (
+        <li key={tile}>
+          <Card className="h-full p-16">
+            <div className="flex items-center justify-between gap-12">
+              <div className="flex min-w-0 items-center gap-12">
+                <Skeleton className="size-24 shrink-0" />
+                <Skeleton className="h-16 w-100" />
+              </div>
+              <Skeleton className="h-16 w-64 shrink-0" />
+            </div>
+          </Card>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/components/redirect-install-page.test.tsx

@@ -0,0 +1,98 @@
+// @vitest-environment jsdom
+import '@testing-library/jest-dom/vitest';
+import {ApiError} from '@shipfox/client-api';
+import {screen, waitFor} from '@testing-library/react';
+import {StrictMode} from 'react';
+import {INTEGRATIONS_TEST_WID, renderIntegrationsPage} from '#test/render.js';
+import {RedirectInstallPage} from './redirect-install-page.js';
+
+function renderInstallPage(
+  props: Parameters<typeof RedirectInstallPage>[0],
+  options?: {strict?: boolean},
+) {
+  return renderIntegrationsPage({
+    path: `/workspaces/${INTEGRATIONS_TEST_WID}/integrations/github`,
+    routePath: '/workspaces/$wid/integrations/github',
+    element: options?.strict ? (
+      <StrictMode>
+        <RedirectInstallPage {...props} />
+      </StrictMode>
+    ) : (
+      <RedirectInstallPage {...props} />
+    ),
+    extraRoutes: ['/workspaces/$wid/integrations'],
+  });
+}
+
+describe('RedirectInstallPage', () => {
+  test('requests the install URL and leaves the app', async () => {
+    const installRequest = vi
+      .fn()
+      .mockResolvedValue({install_url: 'https://provider.test/install'});
+    const assignLocation = vi.fn();
+    const beforeRedirect = vi.fn();
+
+    renderInstallPage({
+      installRequest,
+      errorFallbackMessage: 'Could not start install.',
+      beforeRedirect,
+      assignLocation,
+    });
+
+    await waitFor(() =>
+      expect(assignLocation).toHaveBeenCalledWith('https://provider.test/install'),
+    );
+    expect(installRequest).toHaveBeenCalledWith({workspace_id: INTEGRATIONS_TEST_WID});
+    expect(beforeRedirect).toHaveBeenCalledWith(INTEGRATIONS_TEST_WID);
+    expect(beforeRedirect.mock.invocationCallOrder[0]).toBeLessThan(
+      installRequest.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY,
+    );
+  });
+
+  test('shows the API error message with a back link on failure', async () => {
+    const installRequest = vi
+      .fn()
+      .mockRejectedValue(
+        new ApiError({message: 'Sentry app not configured', code: 'bad-config', status: 422}),
+      );
+
+    renderInstallPage({
+      installRequest,
+      errorFallbackMessage: 'Could not start install.',
+      assignLocation: vi.fn(),
+    });
+
+    // Alert mounts via framer-motion (opacity 0 in jsdom), so assert presence.
+    expect(await screen.findByText('Sentry app not configured')).toBeInTheDocument();
+    expect(screen.getByRole('link', {name: 'Back to integrations'})).toBeVisible();
+  });
+
+  test('requests the install URL exactly once in Strict Mode', async () => {
+    const installRequest = vi
+      .fn()
+      .mockResolvedValue({install_url: 'https://provider.test/install'});
+
+    renderInstallPage(
+      {
+        installRequest,
+        errorFallbackMessage: 'Could not start install.',
+        assignLocation: vi.fn(),
+      },
+      {strict: true},
+    );
+
+    await waitFor(() => expect(installRequest).toHaveBeenCalledTimes(1));
+  });
+
+  test('falls back to the provided message for unknown errors', async () => {
+    const installRequest = vi.fn().mockRejectedValue(new Error('network down'));
+
+    renderInstallPage({
+      installRequest,
+      errorFallbackMessage: 'Could not start install.',
+      assignLocation: vi.fn(),
+    });
+
+    expect(await screen.findByText('Could not start install.')).toBeInTheDocument();
+  });
+});