@shipfox/client-integrations 12.0.2 → 14.0.0

package/src/components/provider-grid.tsx

@@ -11,12 +11,12 @@ import type {IntegrationProvider} from '#core/models.js';
 import {PROVIDER_CATALOG} from '#provider-catalog.js';
 
 export interface ProviderGridProps {
+  workspaceSlug: string;
   providers: IntegrationProvider[];
   isPending: boolean;
   isFetching?: boolean;
   error?: Error | null | undefined;
   onRetry?: () => void;
-  workspaceId: string;
   emptyMessage: string;
   loadingLabel?: string;
   errorSubject?: string;
@@ -29,12 +29,12 @@ export const PROVIDER_SURFACE_CLASS =
   'overflow-hidden rounded-8 border border-border-neutral-base bg-background-neutral-base';
 
 export function ProviderGrid({
+  workspaceSlug,
   providers,
   isPending,
   isFetching = false,
   error,
   onRetry,
-  workspaceId,
   emptyMessage,
   loadingLabel = 'Loading providers',
   errorSubject = 'available integrations',
@@ -79,7 +79,7 @@ export function ProviderGrid({
         <li key={provider.provider}>
           <ProviderCard
             provider={provider}
-            workspaceId={workspaceId}
+            workspaceSlug={workspaceSlug}
             onOpenProvider={onOpenProvider}
           />
         </li>
@@ -90,11 +90,11 @@ export function ProviderGrid({
 
 function ProviderCard({
   provider,
-  workspaceId,
+  workspaceSlug,
   onOpenProvider,
 }: {
   provider: IntegrationProvider;
-  workspaceId: string;
+  workspaceSlug: string;
   onOpenProvider?: ((provider: string) => void) | undefined;
 }) {
   const catalog = PROVIDER_CATALOG[provider.provider];
@@ -116,7 +116,7 @@ function ProviderCard({
   return (
     <Link
       to={catalog.setupPath}
-      params={{wid: workspaceId}}
+      params={{workspaceSlug}}
       aria-label={`Install ${provider.displayName}`}
       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"
     >

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

@@ -11,8 +11,8 @@ function renderInstallPage(
   options?: {strict?: boolean},
 ) {
   return renderIntegrationsPage({
-    path: `/workspaces/${INTEGRATIONS_TEST_WID}/integrations/github`,
-    routePath: '/workspaces/$wid/integrations/github',
+    path: '/w/acme/integrations/github',
+    routePath: '/w/$workspaceSlug/integrations/github',
     element: options?.strict ? (
       <StrictMode>
         <RedirectInstallPage {...props} />
@@ -20,7 +20,7 @@ function renderInstallPage(
     ) : (
       <RedirectInstallPage {...props} />
     ),
-    extraRoutes: ['/workspaces/$wid/integrations'],
+    extraRoutes: ['/w/$workspaceSlug/integrations'],
   });
 }
 

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

@@ -14,7 +14,7 @@ interface RedirectInstallPageProps {
   loadingLabel?: string;
   /**
    * Runs before leaving the app (e.g. to persist the workspace id for a
-   * state-less provider callback). Must not throw — a failed side effect
+   * state-less provider callback. It must not throw. A failed side effect
    * should never block the redirect.
    */
   beforeRedirect?: (workspaceId: string) => void;
@@ -59,7 +59,7 @@ export function RedirectInstallPage({
           <Text size="sm">{errorMessage}</Text>
         </Callout>
         <ButtonLink asChild variant="muted" className="w-fit">
-          <Link to="/workspaces/$wid/integrations" params={{wid: workspace.id}}>
+          <Link to="/w/$workspaceSlug/integrations" params={{workspaceSlug: workspace.slug}}>
             Back to integrations
           </Link>
         </ButtonLink>

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

@@ -176,7 +176,7 @@ function createStoryRouter(scenario: Scenario) {
   const rootRoute = createRootRoute({component: Outlet});
   const workspaceRoute = createRoute({
     getParentRoute: () => rootRoute,
-    path: '/workspaces/$wid',
+    path: '/w/$workspaceSlug',
     component: Outlet,
   });
   const integrationsRoute = createRoute({
@@ -192,7 +192,7 @@ function createStoryRouter(scenario: Scenario) {
 
   return createRouter({
     history: createMemoryHistory({
-      initialEntries: [`/workspaces/${WORKSPACE_ID}/settings/integrations`],
+      initialEntries: ['/w/acme/settings/integrations'],
     }),
     routeTree: rootRoute.addChildren([
       workspaceRoute.addChildren([integrationsRoute, eventsRoute]),

package/src/core/models.ts

@@ -7,6 +7,13 @@ export interface IntegrationProvider {
   capabilities: IntegrationCapability[];
 }
 
+export interface JiraSite {
+  cloudId: string;
+  name: string;
+  url: string;
+  scopes: string[];
+}
+
 export interface IntegrationConnection {
   id: string;
   workspaceId: string;
@@ -163,6 +170,15 @@ const linearUsageEvents = [
 
 const sentryIssueActions = ['created', 'resolved', 'assigned', 'archived', 'unresolved'] as const;
 
+const jiraUsageEvents = [
+  'jira:issue_created',
+  'jira:issue_updated',
+  'jira:issue_deleted',
+  'comment_created',
+  'comment_updated',
+  'comment_deleted',
+] as const;
+
 export function usageEventsForConnection(
   connection: Pick<IntegrationConnection, 'provider' | 'capabilities'>,
 ): IntegrationUsageEvent[] {
@@ -174,6 +190,8 @@ export function usageEventsForConnection(
       value: `issue.${action}`,
       label: `issue.${action}`,
     }));
+  if (connection.provider === 'jira')
+    return jiraUsageEvents.map((value) => ({value, label: value}));
   if (connection.provider === 'linear')
     return linearUsageEvents.map((value) => ({value, label: value}));
   if (connection.capabilities.includes('source_control')) return [{value: 'push', label: 'push'}];

package/src/feature.ts

@@ -23,6 +23,11 @@ export const integrationsFeature = defineClientFeature({
       parent: 'root',
       impl: '@shipfox/client-integrations/routes/linear-callback',
     },
+    {
+      path: '/integrations/jira/callback',
+      parent: 'root',
+      impl: '@shipfox/client-integrations/routes/jira-callback',
+    },
     {
       path: '/integrations/sentry/callback',
       parent: 'root',
@@ -34,37 +39,42 @@ export const integrationsFeature = defineClientFeature({
       impl: '@shipfox/client-integrations/routes/slack-callback',
     },
     {
-      path: '/workspaces/$wid/integrations',
+      path: '/w/$workspaceSlug/integrations',
       parent: 'workspaceLayout',
       impl: '@shipfox/client-integrations/routes/integrations',
     },
     {
-      path: '/workspaces/$wid/integrations/gitea',
+      path: '/w/$workspaceSlug/integrations/gitea',
       parent: 'workspaceLayout',
       impl: '@shipfox/client-integrations/routes/gitea',
     },
     {
-      path: '/workspaces/$wid/integrations/github',
+      path: '/w/$workspaceSlug/integrations/github',
       parent: 'workspaceLayout',
       impl: '@shipfox/client-integrations/routes/github',
     },
     {
-      path: '/workspaces/$wid/integrations/linear',
+      path: '/w/$workspaceSlug/integrations/linear',
       parent: 'workspaceLayout',
       impl: '@shipfox/client-integrations/routes/linear',
     },
     {
-      path: '/workspaces/$wid/integrations/sentry',
+      path: '/w/$workspaceSlug/integrations/jira',
+      parent: 'workspaceLayout',
+      impl: '@shipfox/client-integrations/routes/jira',
+    },
+    {
+      path: '/w/$workspaceSlug/integrations/sentry',
       parent: 'workspaceLayout',
       impl: '@shipfox/client-integrations/routes/sentry',
     },
     {
-      path: '/workspaces/$wid/integrations/slack',
+      path: '/w/$workspaceSlug/integrations/slack',
       parent: 'workspaceLayout',
       impl: '@shipfox/client-integrations/routes/slack',
     },
     {
-      path: '/workspaces/$wid/settings/integrations',
+      path: '/w/$workspaceSlug/settings/integrations',
       parent: 'workspaceSettings',
       impl: '@shipfox/client-integrations/routes/integrations-settings',
     },

package/src/hooks/api/integration-mapper.ts

@@ -3,11 +3,13 @@ import type {
   IntegrationProviderDto,
   RepositoryDto,
 } from '@shipfox/api-integration-core-dto';
+import type {JiraAccessibleResourceDto} from '@shipfox/api-integration-jira-dto';
 import type {WebhookConnectionDto} from '@shipfox/api-integration-webhook-dto';
 import type {
   InstallRedirect,
   IntegrationConnection,
   IntegrationProvider,
+  JiraSite,
   Repository,
   WebhookConnection,
 } from '#core/models.js';
@@ -20,6 +22,10 @@ export function toInstallRedirect(dto: {install_url: string}): InstallRedirect {
   return {installUrl: dto.install_url};
 }
 
+export function toJiraSite(dto: JiraAccessibleResourceDto): JiraSite {
+  return {cloudId: dto.cloud_id, name: dto.name, url: dto.url, scopes: dto.scopes};
+}
+
 export function toIntegrationConnection(dto: IntegrationConnectionDto): IntegrationConnection {
   return {
     id: dto.id,

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

@@ -1,8 +1,11 @@
 import type {IntegrationConnectionDto} from '@shipfox/api-integration-core-dto';
 import {configureApiClient} from '@shipfox/client-api';
 import {
+  completeJiraCallback,
+  completeJiraSiteSelection,
   completeLinearCallback,
   completeSlackCallback,
+  createJiraInstall,
   createLinearInstall,
   createSlackInstall,
   listSourceConnections,
@@ -155,3 +158,92 @@ describe('Linear transport', () => {
     );
   });
 });
+
+describe('Jira transport', () => {
+  it('posts the install workspace, maps multi-site callbacks, and completes a site selection', async () => {
+    const requests: Request[] = [];
+    const connectionBody = {
+      id: '33333333-3333-4333-8333-333333333333',
+      workspace_id: '11111111-1111-4111-8111-111111111111',
+      provider: 'jira',
+      external_account_id: 'cloud-1',
+      slug: 'jira_acme',
+      display_name: 'Jira Acme',
+      lifecycle_status: 'active',
+      capabilities: ['agent_tools'],
+      created_at: '2026-01-01T00:00:00.000Z',
+      updated_at: '2026-01-01T00:00:00.000Z',
+    };
+    configureApiClient({
+      baseUrl: 'https://api.example.test',
+      fetchImpl: vi.fn((input, init) => {
+        const request = new Request(input, init);
+        requests.push(request);
+        if (request.url.endsWith('/install'))
+          return Promise.resolve(jsonResponse({install_url: 'https://jira.example.test/install'}));
+        if (request.url.endsWith('/callback/site'))
+          return Promise.resolve(jsonResponse(connectionBody));
+        return Promise.resolve(
+          jsonResponse({
+            sites: [
+              {
+                cloud_id: 'cloud-1',
+                name: 'Acme',
+                url: 'https://acme.atlassian.net',
+                scopes: ['read:jira-work'],
+              },
+              {
+                cloud_id: 'cloud-2',
+                name: 'Beta',
+                url: 'https://beta.atlassian.net',
+                scopes: ['read:jira-work'],
+              },
+            ],
+          }),
+        );
+      }),
+    });
+
+    const install = await createJiraInstall({
+      workspace_id: '11111111-1111-4111-8111-111111111111',
+    });
+    const sites = await completeJiraCallback({
+      query: {code: 'grant code', state: 'signed state'},
+      token: 'session-token',
+    });
+    const connection = await completeJiraSiteSelection({
+      body: {cloud_id: 'cloud-1', state: 'signed state'},
+      token: 'session-token',
+    });
+
+    expect(install).toEqual({installUrl: 'https://jira.example.test/install'});
+    expect(sites).toEqual({
+      sites: [
+        {
+          cloudId: 'cloud-1',
+          name: 'Acme',
+          url: 'https://acme.atlassian.net',
+          scopes: ['read:jira-work'],
+        },
+        {
+          cloudId: 'cloud-2',
+          name: 'Beta',
+          url: 'https://beta.atlassian.net',
+          scopes: ['read:jira-work'],
+        },
+      ],
+    });
+    expect(connection.provider).toBe('jira');
+    expect(requests[0]?.url).toBe('https://api.example.test/integrations/jira/install');
+    expect(await requests[0]?.json()).toEqual({
+      workspace_id: '11111111-1111-4111-8111-111111111111',
+    });
+    expect(requests[1]?.url).toBe(
+      'https://api.example.test/integrations/jira/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/jira/callback/site');
+    expect(await requests[2]?.json()).toEqual({cloud_id: 'cloud-1', state: 'signed state'});
+    expect(requests[2]?.headers.get('authorization')).toBe('Bearer session-token');
+  });
+});

package/src/hooks/api/integrations.ts

@@ -15,6 +15,15 @@ import {
   createGithubInstallResponseSchema,
   githubCallbackResponseSchema,
 } from '@shipfox/api-integration-github-dto';
+import type {
+  CompleteJiraSiteSelectionBodyDto,
+  CreateJiraInstallBodyDto,
+  JiraCallbackQueryDto,
+} from '@shipfox/api-integration-jira-dto';
+import {
+  createJiraInstallResponseSchema,
+  jiraCallbackResponseSchema,
+} from '@shipfox/api-integration-jira-dto';
 import type {
   CreateLinearInstallBodyDto,
   LinearCallbackQueryDto,
@@ -56,14 +65,17 @@ import {
   type IntegrationConnection,
   type IntegrationProvider,
   isUsableConnection,
+  type JiraSite,
   type RepositoryPage,
 } from '#core/models.js';
+import {serializeJiraCallbackQuery} from '#jira-callback.js';
 import {serializeLinearCallbackQuery} from '#linear-callback.js';
 import {serializeSlackCallbackQuery} from '#slack-callback.js';
 import {
   toInstallRedirect,
   toIntegrationConnection,
   toIntegrationProvider,
+  toJiraSite,
   toRepository,
 } from './integration-mapper.js';
 
@@ -175,7 +187,7 @@ export async function listSourceConnections({
   });
   // The endpoint returns every lifecycle status (the settings hub needs that),
   // but source-control consumers (onboarding redirect, project creation) only
-  // act on usable connections — a disabled/error one must read as "not there".
+  // act on usable connections. A disabled/error one must read as "not there".
   return connections.filter(isUsableConnection);
 }
 
@@ -261,6 +273,15 @@ export async function createLinearInstall(
   );
 }
 
+export async function createJiraInstall(body: CreateJiraInstallBodyDto): Promise<InstallRedirect> {
+  return toInstallRedirect(
+    await checkedApiRequest(createJiraInstallResponseSchema, '/integrations/jira/install', {
+      method: 'POST',
+      body,
+    }),
+  );
+}
+
 export async function createSlackInstall(
   body: CreateSlackInstallBodyDto,
 ): Promise<InstallRedirect> {
@@ -302,6 +323,44 @@ export async function completeSlackCallback({
   return toIntegrationConnection(response);
 }
 
+export type JiraCallbackResult = IntegrationConnection | {sites: JiraSite[]};
+
+export async function completeJiraCallback({
+  query,
+  token,
+}: {
+  query: JiraCallbackQueryDto;
+  token: string;
+}): Promise<JiraCallbackResult> {
+  const response = await checkedApiRequest(
+    jiraCallbackResponseSchema,
+    `/integrations/jira/callback/api?${serializeJiraCallbackQuery(query)}`,
+    {headers: {authorization: `Bearer ${token}`}},
+  );
+  return 'sites' in response
+    ? {sites: response.sites.map(toJiraSite)}
+    : toIntegrationConnection(response);
+}
+
+export async function completeJiraSiteSelection({
+  body,
+  token,
+}: {
+  body: CompleteJiraSiteSelectionBodyDto;
+  token: string;
+}): Promise<IntegrationConnection> {
+  const response = await checkedApiRequest(
+    integrationConnectionDtoSchema,
+    '/integrations/jira/callback/site',
+    {
+      method: 'POST',
+      body,
+      headers: {authorization: `Bearer ${token}`},
+    },
+  );
+  return toIntegrationConnection(response);
+}
+
 // Called from the callback route with an explicit bearer (same as the GitHub
 // callback): the route refreshes auth itself before forwarding the grant code.
 export async function connectSentry({body, token}: {body: SentryConnectBodyDto; token: string}) {
@@ -452,6 +511,10 @@ export function useCreateSlackInstallMutation() {
   return useMutation({mutationFn: createSlackInstall});
 }
 
+export function useCreateJiraInstallMutation() {
+  return useMutation({mutationFn: createJiraInstall});
+}
+
 export function useCompleteLinearCallbackMutation() {
   return useMutation({mutationFn: completeLinearCallback});
 }
@@ -460,6 +523,14 @@ export function useCompleteSlackCallbackMutation() {
   return useMutation({mutationFn: completeSlackCallback});
 }
 
+export function useCompleteJiraCallbackMutation() {
+  return useMutation({mutationFn: completeJiraCallback});
+}
+
+export function useCompleteJiraSiteSelectionMutation() {
+  return useMutation({mutationFn: completeJiraSiteSelection});
+}
+
 export function useUpdateIntegrationConnectionMutation() {
   const queryClient = useQueryClient();
   return useMutation({

package/src/index.ts

@@ -6,8 +6,12 @@ export * from './components/redirect-install-page.js';
 export * from './components/repository-picker.js';
 export * from './connection-status-badge.js';
 export * from './hooks/api/integrations.js';
+export * from './jira-callback.js';
+export * from './jira-form-errors.js';
 export * from './pages/gitea-install-page.js';
 export * from './pages/github-install-page.js';
+export * from './pages/jira-callback-page.js';
+export * from './pages/jira-install-page.js';
 export * from './pages/linear-callback-page.js';
 export * from './pages/linear-install-page.js';
 export * from './pages/sentry-callback-page.js';

package/src/jira-callback-state.ts

@@ -0,0 +1,19 @@
+import {createSingleFlight} from '@shipfox/client-ui';
+import type {IntegrationConnection} from '#core/models.js';
+import type {JiraCallbackResult} from '#hooks/api/integrations.js';
+
+export const JIRA_CALLBACK_CACHE_SIZE = 32;
+
+export const jiraCallbackRequests = createSingleFlight<string, JiraCallbackResult>({
+  maxTerminalResults: JIRA_CALLBACK_CACHE_SIZE,
+});
+export const jiraSiteSelectionRequests = createSingleFlight<string, IntegrationConnection>();
+export const jiraCompletedConnections = new Map<string, IntegrationConnection>();
+export const jiraToastedCallbacks = new Set<string>();
+
+export function resetJiraCallbackState(): void {
+  jiraCallbackRequests.clear();
+  jiraSiteSelectionRequests.clear();
+  jiraCompletedConnections.clear();
+  jiraToastedCallbacks.clear();
+}

package/src/jira-callback.test.ts

@@ -0,0 +1,76 @@
+import {
+  clearJiraInstallWorkspace,
+  JIRA_INSTALL_WORKSPACE_KEY,
+  parseJiraCallbackQuery,
+  readJiraInstallWorkspace,
+  saveJiraInstallWorkspace,
+  serializeJiraCallbackQuery,
+} from './jira-callback.js';
+
+describe('Jira callback helpers', () => {
+  it('parses and serializes success and provider-error callback queries', () => {
+    const success = parseJiraCallbackQuery({code: 'grant code', state: 'signed state'});
+    const providerError = parseJiraCallbackQuery({
+      error: 'access_denied',
+      error_description: 'User denied access',
+      state: 'signed state',
+    });
+
+    expect(success).toEqual({code: 'grant code', state: 'signed state'});
+    expect(providerError).toEqual({
+      error: 'access_denied',
+      error_description: 'User denied access',
+      state: 'signed state',
+    });
+    expect(success && serializeJiraCallbackQuery(success)).toBe(
+      'code=grant+code&state=signed+state',
+    );
+    expect(providerError && serializeJiraCallbackQuery(providerError)).toBe(
+      'error=access_denied&error_description=User+denied+access&state=signed+state',
+    );
+  });
+
+  it('rejects malformed callback queries and prefers a grant code', () => {
+    expect(parseJiraCallbackQuery({code: 'grant'})).toBeUndefined();
+    expect(parseJiraCallbackQuery({state: 'signed'})).toBeUndefined();
+    expect(parseJiraCallbackQuery({error: 'access_denied'})).toBeUndefined();
+    expect(parseJiraCallbackQuery({state: ['a', 'b']})).toBeUndefined();
+    expect(
+      parseJiraCallbackQuery({
+        code: 'grant',
+        error: 'access_denied',
+        state: 'signed',
+      }),
+    ).toEqual({code: 'grant', state: 'signed'});
+  });
+
+  it('round-trips workspace navigation storage and swallows storage errors', () => {
+    const storage = new Map<string, string>();
+    const workspaceStorage = {
+      getItem: (key: string) => storage.get(key) ?? null,
+      setItem: (key: string, value: string) => storage.set(key, value),
+      removeItem: (key: string) => storage.delete(key),
+    };
+
+    saveJiraInstallWorkspace(workspaceStorage, 'workspace-1');
+    expect(storage.get(JIRA_INSTALL_WORKSPACE_KEY)).toBe('workspace-1');
+    expect(readJiraInstallWorkspace(workspaceStorage)).toBe('workspace-1');
+    clearJiraInstallWorkspace(workspaceStorage);
+    expect(readJiraInstallWorkspace(workspaceStorage)).toBeUndefined();
+
+    const unavailableStorage = {
+      getItem: () => {
+        throw new Error('unavailable');
+      },
+      setItem: () => {
+        throw new Error('unavailable');
+      },
+      removeItem: () => {
+        throw new Error('unavailable');
+      },
+    };
+    expect(() => saveJiraInstallWorkspace(unavailableStorage, 'workspace-1')).not.toThrow();
+    expect(() => readJiraInstallWorkspace(unavailableStorage)).not.toThrow();
+    expect(() => clearJiraInstallWorkspace(unavailableStorage)).not.toThrow();
+  });
+});

package/src/jira-callback.ts

@@ -0,0 +1,67 @@
+import type {JiraCallbackQueryDto} from '@shipfox/api-integration-jira-dto';
+import {
+  type BrowserStorage,
+  type BrowserStorageKey,
+  createTypedBrowserStorage,
+} from '@shipfox/client-ui';
+
+export const JIRA_INSTALL_WORKSPACE_KEY = 'shipfox.jira-install.workspace-id';
+
+type WorkspaceStorage = BrowserStorage | undefined;
+
+const jiraInstallWorkspaceStorageKey = {
+  key: JIRA_INSTALL_WORKSPACE_KEY,
+  lifetime: 'session',
+  // This is a one-shot navigation hint, not private workspace state. It must
+  // remain readable on an OAuth callback before workspace hydration completes;
+  // the signed callback state and returned connection are authoritative.
+  principalScope: 'global',
+  serialize: (workspaceId: string) => workspaceId,
+  parse: (value: string) => value || undefined,
+} satisfies BrowserStorageKey<string>;
+
+export function saveJiraInstallWorkspace(storage: WorkspaceStorage, workspaceId: string): void {
+  installWorkspaceStorage(storage).write(workspaceId);
+}
+
+export function readJiraInstallWorkspace(storage: WorkspaceStorage): string | undefined {
+  return installWorkspaceStorage(storage).read();
+}
+
+export function clearJiraInstallWorkspace(storage: WorkspaceStorage): void {
+  installWorkspaceStorage(storage).remove();
+}
+
+function installWorkspaceStorage(storage: WorkspaceStorage) {
+  return createTypedBrowserStorage(() => storage, jiraInstallWorkspaceStorageKey);
+}
+
+export function parseJiraCallbackQuery(
+  search: Record<string, unknown>,
+): JiraCallbackQueryDto | undefined {
+  const state = stringParam(search.state);
+  if (!state) return undefined;
+
+  const code = stringParam(search.code);
+  if (code) return {code, state};
+
+  const error = stringParam(search.error);
+  if (!error) return undefined;
+  const errorDescription = stringParam(search.error_description);
+  return errorDescription ? {error, error_description: errorDescription, state} : {error, state};
+}
+
+export function serializeJiraCallbackQuery(query: JiraCallbackQueryDto): string {
+  const params = new URLSearchParams();
+  if ('code' in query) params.set('code', query.code);
+  else {
+    params.set('error', query.error);
+    if (query.error_description) params.set('error_description', query.error_description);
+  }
+  params.set('state', query.state);
+  return params.toString();
+}
+
+function stringParam(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}