@shipfox/client-integrations 0.2.0

package/src/components/webhook/webhook-modals.stories.tsx

@@ -0,0 +1,225 @@
+import type {IntegrationConnectionDto} from '@shipfox/api-integration-core-dto';
+import type {WebhookConnectionDto} from '@shipfox/api-integration-webhook-dto';
+import {WEBHOOK_RECEIVED_EVENT} from '@shipfox/api-integration-webhook-dto';
+import {configureApiClient} from '@shipfox/client-api';
+import {Toaster} from '@shipfox/react-ui/toast';
+import type {Meta, StoryObj} from '@storybook/react';
+import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+  Outlet,
+  RouterProvider,
+} from '@tanstack/react-router';
+import {useMemo} from 'react';
+import {IntegrationDeleteConfirmModal} from '../integration-delete-confirm-modal.js';
+import {IntegrationUsageModal} from '../integration-usage-modal.js';
+import {CopyableValue} from './copyable-value.js';
+import {WebhookCreateModal} from './webhook-create-modal.js';
+import {WebhookPublicEndpointAlert} from './webhook-public-endpoint-alert.js';
+import {WebhookUsageDetails} from './webhook-usage-details.js';
+
+const WORKSPACE_ID = '11111111-1111-4111-8111-111111111111';
+const CONNECTION_ID = '77777777-7777-4777-8777-777777777777';
+
+type Scenario =
+  | 'create-form'
+  | 'create-success'
+  | 'usage-active'
+  | 'usage-disabled'
+  | 'delete-confirm'
+  | 'copyable-value';
+
+interface WebhookModalStoryProps {
+  scenario: Scenario;
+}
+
+const activeConnection: WebhookConnectionDto = {
+  id: CONNECTION_ID,
+  workspace_id: WORKSPACE_ID,
+  name: 'Stripe production',
+  slug: 'stripe-prod',
+  lifecycle_status: 'active',
+  inbound_url: 'https://api.example.test/webhook/77777777-7777-4777-8777-777777777777',
+  created_at: '2026-04-12T00:00:00.000Z',
+  updated_at: '2026-04-12T00:00:00.000Z',
+};
+
+const disabledConnection: WebhookConnectionDto = {
+  ...activeConnection,
+  lifecycle_status: 'disabled',
+};
+
+const activeIntegrationConnection: IntegrationConnectionDto = {
+  id: CONNECTION_ID,
+  workspace_id: WORKSPACE_ID,
+  provider: 'webhook',
+  external_account_id: activeConnection.slug,
+  slug: activeConnection.slug,
+  display_name: activeConnection.name,
+  lifecycle_status: activeConnection.lifecycle_status,
+  capabilities: [],
+  created_at: activeConnection.created_at,
+  updated_at: activeConnection.updated_at,
+};
+
+const disabledIntegrationConnection: IntegrationConnectionDto = {
+  ...activeIntegrationConnection,
+  lifecycle_status: 'disabled',
+};
+
+function WebhookModalStory({scenario}: WebhookModalStoryProps) {
+  const connection = scenario === 'usage-disabled' ? disabledConnection : activeConnection;
+
+  configureApiClient({
+    baseUrl: 'https://api.example.test',
+    fetchImpl: fetchForConnection(connection),
+  });
+
+  const queryClient = useMemo(
+    () => new QueryClient({defaultOptions: {queries: {retry: false}}}),
+    [],
+  );
+  const router = useMemo(() => createStoryRouter(scenario), [scenario]);
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <RouterProvider router={router} />
+      <Toaster />
+    </QueryClientProvider>
+  );
+}
+
+const meta = {
+  title: 'Integrations/WebhookModals',
+  component: WebhookModalStory,
+  parameters: {layout: 'fullscreen'},
+  args: {scenario: 'create-form'},
+} satisfies Meta<typeof WebhookModalStory>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {};
+
+export const CreateSuccess: Story = {
+  args: {scenario: 'create-success'},
+};
+
+export const UsageActive: Story = {
+  args: {scenario: 'usage-active'},
+};
+
+export const UsageDisabled: Story = {
+  args: {scenario: 'usage-disabled'},
+};
+
+export const DeleteConfirm: Story = {
+  args: {scenario: 'delete-confirm'},
+};
+
+export const CopyableValueState: Story = {
+  args: {scenario: 'copyable-value'},
+};
+
+function StorySurface({scenario}: {scenario: Scenario}) {
+  return (
+    <div className="min-h-screen bg-background-neutral-background p-24">
+      {scenario === 'create-form' ? (
+        <WebhookCreateModal
+          workspaceId={WORKSPACE_ID}
+          open
+          onOpenChange={() => undefined}
+          onCreated={() => undefined}
+        />
+      ) : null}
+      {scenario === 'create-success' ||
+      scenario === 'usage-active' ||
+      scenario === 'usage-disabled' ? (
+        <IntegrationUsageModal
+          connection={
+            scenario === 'usage-disabled'
+              ? disabledIntegrationConnection
+              : activeIntegrationConnection
+          }
+          events={[{value: WEBHOOK_RECEIVED_EVENT, label: WEBHOOK_RECEIVED_EVENT}]}
+          open
+          onOpenChange={() => undefined}
+        >
+          <WebhookUsageDetails workspaceId={WORKSPACE_ID} connectionId={CONNECTION_ID} />
+        </IntegrationUsageModal>
+      ) : null}
+      {scenario === 'delete-confirm' ? (
+        <IntegrationDeleteConfirmModal
+          connectionName={activeConnection.name}
+          open
+          isPending={false}
+          onOpenChange={() => undefined}
+          onConfirm={() => undefined}
+        />
+      ) : null}
+      {scenario === 'copyable-value' ? (
+        <div className="mx-auto max-w-[560px] rounded-8 border border-border-neutral-base bg-background-neutral-base p-24">
+          <div className="flex flex-col gap-12">
+            <CopyableValue label="inbound URL" value={activeConnection.inbound_url} />
+            <WebhookPublicEndpointAlert />
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function createStoryRouter(scenario: Scenario) {
+  const rootRoute = createRootRoute({component: Outlet});
+  const workspaceRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: '/workspaces/$wid',
+    component: Outlet,
+  });
+  const integrationsRoute = createRoute({
+    getParentRoute: () => workspaceRoute,
+    path: 'settings/integrations',
+    component: () => <StorySurface scenario={scenario} />,
+  });
+  const eventsRoute = createRoute({
+    getParentRoute: () => workspaceRoute,
+    path: 'settings/events',
+    component: () => <div />,
+  });
+
+  return createRouter({
+    history: createMemoryHistory({
+      initialEntries: [`/workspaces/${WORKSPACE_ID}/settings/integrations`],
+    }),
+    routeTree: rootRoute.addChildren([
+      workspaceRoute.addChildren([integrationsRoute, eventsRoute]),
+    ]),
+  });
+}
+
+function fetchForConnection(connection: WebhookConnectionDto): typeof fetch {
+  return (input) => {
+    const url = requestUrl(input);
+    if (url.pathname === '/integrations/webhook/connections') {
+      return Promise.resolve(jsonResponse({connections: [connection]}));
+    }
+    return Promise.resolve(jsonResponse({}, {status: 404}));
+  };
+}
+
+function requestUrl(input: RequestInfo | URL): URL {
+  if (typeof input === 'string') return new URL(input);
+  if (input instanceof URL) return input;
+  return new URL(input.url);
+}
+
+function jsonResponse(body: unknown, init: ResponseInit = {}) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {'content-type': 'application/json'},
+    ...init,
+  });
+}

package/src/components/webhook/webhook-public-endpoint-alert.tsx

@@ -0,0 +1,15 @@
+import {Callout, CalloutContent, CalloutDescription, CalloutTitle} from '@shipfox/react-ui/callout';
+
+export function WebhookPublicEndpointAlert() {
+  return (
+    <Callout role="alert" type="default">
+      <CalloutContent>
+        <CalloutTitle>Public webhook endpoint</CalloutTitle>
+        <CalloutDescription>
+          Anyone with this URL can send webhook events to this source. You are responsible for
+          verifying the received webhook in your workflow before trusting its payload.
+        </CalloutDescription>
+      </CalloutContent>
+    </Callout>
+  );
+}

package/src/components/webhook/webhook-usage-details.tsx

@@ -0,0 +1,44 @@
+import {QueryLoadError} from '@shipfox/client-ui';
+import {ShipfoxLoader} from '@shipfox/react-ui/loader';
+import {Text} from '@shipfox/react-ui/typography';
+import {useWebhookConnectionsQuery} from '#hooks/api/webhook-connections.js';
+import {CopyableValue} from './copyable-value.js';
+import {WebhookPublicEndpointAlert} from './webhook-public-endpoint-alert.js';
+
+interface WebhookUsageDetailsProps {
+  workspaceId: string;
+  connectionId: string;
+}
+
+export function WebhookUsageDetails({workspaceId, connectionId}: WebhookUsageDetailsProps) {
+  const connectionsQuery = useWebhookConnectionsQuery(workspaceId);
+  const connection = connectionsQuery.data?.connections.find(
+    (candidate) => candidate.id === connectionId,
+  );
+
+  if (connectionsQuery.isPending) {
+    return (
+      <div className="flex min-h-80 items-center justify-center">
+        <ShipfoxLoader size={32} animation="circular" color="orange" background="light" />
+      </div>
+    );
+  }
+
+  if (connectionsQuery.isError && connectionsQuery.data === undefined) {
+    return <QueryLoadError query={connectionsQuery} subject="webhook details" />;
+  }
+
+  if (!connection) return null;
+
+  return (
+    <div className="flex w-full flex-col gap-16">
+      <div className="flex w-full min-w-0 flex-col gap-8">
+        <Text size="sm" bold>
+          Inbound URL
+        </Text>
+        <CopyableValue label="inbound URL" value={connection.inbound_url} />
+        <WebhookPublicEndpointAlert />
+      </div>
+    </div>
+  );
+}

package/src/connection-status-badge.tsx

@@ -0,0 +1,38 @@
+import type {IntegrationConnectionLifecycleStatusDto} from '@shipfox/api-integration-core-dto';
+import {Badge} from '@shipfox/react-ui/badge';
+import type {IconName} from '@shipfox/react-ui/icon';
+
+const lifecyclePills: Record<
+  IntegrationConnectionLifecycleStatusDto,
+  {variant: 'warning' | 'error'; label: string; iconLeft?: IconName} | undefined
+> = {
+  // `active` is the expected state and carries no badge.
+  active: undefined,
+  disabled: {variant: 'warning', label: 'Disabled', iconLeft: 'errorWarningLine'},
+  error: {variant: 'error', label: 'Error'},
+};
+
+export interface ConnectionStatusBadgeProps {
+  status: IntegrationConnectionLifecycleStatusDto;
+  className?: string;
+}
+
+/**
+ * Single source of truth for a connection's lifecycle pill, shared by the
+ * integration gallery and any surface that reflects source health. Renders
+ * nothing for the expected `active` state.
+ */
+export function ConnectionStatusBadge({status, className}: ConnectionStatusBadgeProps) {
+  const pill = lifecyclePills[status];
+  if (!pill) return null;
+  return (
+    <Badge
+      variant={pill.variant}
+      radius="rounded"
+      className={className}
+      {...(pill.iconLeft ? {iconLeft: pill.iconLeft} : {})}
+    >
+      {pill.label}
+    </Badge>
+  );
+}

package/src/feature.ts

@@ -0,0 +1,47 @@
+import {defineClientFeature} from '@shipfox/client-shell';
+
+export const integrationsFeature = defineClientFeature({
+  id: 'shipfox.integrations',
+  routes: [
+    {
+      path: '/integrations/github/callback',
+      parent: 'root',
+      impl: '@shipfox/client-integrations/routes/github-callback',
+    },
+    {
+      path: '/integrations/linear/callback',
+      parent: 'root',
+      impl: '@shipfox/client-integrations/routes/linear-callback',
+    },
+    {
+      path: '/integrations/sentry/callback',
+      parent: 'root',
+      impl: '@shipfox/client-integrations/routes/sentry-callback',
+    },
+    {
+      path: '/workspaces/$wid/integrations',
+      parent: 'workspaceLayout',
+      impl: '@shipfox/client-integrations/routes/integrations',
+    },
+    {
+      path: '/workspaces/$wid/integrations/gitea',
+      parent: 'workspaceLayout',
+      impl: '@shipfox/client-integrations/routes/gitea',
+    },
+    {
+      path: '/workspaces/$wid/integrations/github',
+      parent: 'workspaceLayout',
+      impl: '@shipfox/client-integrations/routes/github',
+    },
+    {
+      path: '/workspaces/$wid/integrations/linear',
+      parent: 'workspaceLayout',
+      impl: '@shipfox/client-integrations/routes/linear',
+    },
+    {
+      path: '/workspaces/$wid/integrations/sentry',
+      parent: 'workspaceLayout',
+      impl: '@shipfox/client-integrations/routes/sentry',
+    },
+  ],
+});

package/src/hooks/api/integrations.test.ts

@@ -0,0 +1,105 @@
+import type {IntegrationConnectionDto} from '@shipfox/api-integration-core-dto';
+import {configureApiClient} from '@shipfox/client-api';
+import {
+  completeLinearCallback,
+  createLinearInstall,
+  listSourceConnections,
+} from './integrations.js';
+
+function connection(overrides: Partial<IntegrationConnectionDto> = {}): IntegrationConnectionDto {
+  return {
+    id: 'c1',
+    workspace_id: 'ws-1',
+    provider: 'github',
+    external_account_id: 'acct',
+    slug: 'github_acct',
+    display_name: 'GitHub',
+    lifecycle_status: 'active',
+    capabilities: ['source_control'],
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+function jsonResponse(body: unknown) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {'content-type': 'application/json'},
+  });
+}
+
+describe('listSourceConnections', () => {
+  test('requests the source_control capability and drops non-active connections', async () => {
+    let requestedUrl = '';
+    const fetchImpl = vi.fn((input: RequestInfo | URL) => {
+      requestedUrl =
+        typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+      return Promise.resolve(
+        jsonResponse({
+          connections: [
+            connection({id: 'active-1', lifecycle_status: 'active'}),
+            connection({id: 'disabled-1', lifecycle_status: 'disabled'}),
+            connection({id: 'error-1', lifecycle_status: 'error'}),
+          ],
+        }),
+      );
+    });
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    const result = await listSourceConnections({workspaceId: 'ws-1'});
+
+    expect(requestedUrl).toContain('capability=source_control');
+    expect(result.connections.map((connection) => connection.id)).toEqual(['active-1']);
+  });
+});
+
+describe('Linear transport', () => {
+  it('posts the install workspace and forwards an authenticated callback query', async () => {
+    const requests: Request[] = [];
+    const fetchImpl = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
+      requests.push(new Request(input, init));
+      return Promise.resolve(
+        jsonResponse({
+          id: 'connection-1',
+          workspace_id: '11111111-1111-4111-8111-111111111111',
+          provider: 'linear',
+          external_account_id: 'linear-org',
+          slug: 'linear_org',
+          display_name: 'Linear org',
+          lifecycle_status: 'active',
+          capabilities: [],
+          created_at: '2026-01-01T00:00:00.000Z',
+          updated_at: '2026-01-01T00:00:00.000Z',
+        }),
+      );
+    });
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    await createLinearInstall({workspace_id: '11111111-1111-4111-8111-111111111111'});
+    await completeLinearCallback({
+      query: {code: 'grant code', state: 'signed state'},
+      token: 'session-token',
+    });
+    await completeLinearCallback({
+      query: {
+        error: 'access_denied',
+        error_description: 'User denied access',
+        state: 'signed error state',
+      },
+      token: 'session-token',
+    });
+
+    expect(requests[0]?.url).toBe('https://api.example.test/integrations/linear/install');
+    expect(await requests[0]?.json()).toEqual({
+      workspace_id: '11111111-1111-4111-8111-111111111111',
+    });
+    expect(requests[1]?.url).toBe(
+      'https://api.example.test/integrations/linear/callback/api?code=grant+code&state=signed+state',
+    );
+    expect(requests[1]?.headers.get('authorization')).toBe('Bearer session-token');
+    expect(requests[2]?.url).toBe(
+      'https://api.example.test/integrations/linear/callback/api?error=access_denied&error_description=User+denied+access&state=signed+error+state',
+    );
+  });
+});