@shipfox/api-integration-linear 2.0.0

package/src/api/client.ts

@@ -0,0 +1,281 @@
+import {logger} from '@shipfox/node-opentelemetry';
+import ky, {HTTPError, TimeoutError} from 'ky';
+import {config} from '#config.js';
+import {LinearIntegrationProviderError} from '#core/errors.js';
+
+const LINEAR_OAUTH_TOKEN_URL = 'https://api.linear.app/oauth/token';
+const LINEAR_OAUTH_REVOKE_URL = 'https://api.linear.app/oauth/revoke';
+const LINEAR_GRAPHQL_URL = 'https://api.linear.app/graphql';
+const LINEAR_API_TIMEOUT_MS = 10_000;
+const SCOPE_SEPARATOR_RE = /[,\s]+/;
+
+const IDENTITY_QUERY = `
+  query ShipfoxLinearIdentity {
+    viewer {
+      id
+    }
+    organization {
+      id
+      name
+      urlKey
+    }
+  }
+`;
+
+export interface LinearAuthorization {
+  accessToken: string;
+  refreshToken?: string | undefined;
+  expiresAt?: Date | undefined;
+  scopes: string[];
+}
+
+export interface LinearIdentity {
+  appUserId: string;
+  organizationId: string;
+  organizationName: string;
+  organizationUrlKey: string;
+}
+
+export interface LinearApiClient {
+  exchangeAuthorizationCode(input: {code: string}): Promise<LinearAuthorization>;
+  refreshAccessToken(input: {refreshToken: string}): Promise<LinearAuthorization>;
+  revokeToken(input: {
+    token: string;
+    tokenTypeHint: 'access_token' | 'refresh_token';
+  }): Promise<void>;
+  getIdentity(input: {accessToken: string}): Promise<LinearIdentity>;
+}
+
+interface LinearTokenResponse {
+  access_token?: unknown;
+  refresh_token?: unknown;
+  expires_in?: unknown;
+  scope?: unknown;
+}
+
+interface LinearGraphqlResponse<Data> {
+  data?: Data | null;
+  errors?: LinearGraphqlError[] | undefined;
+}
+
+interface LinearGraphqlError {
+  extensions?: {type?: unknown} | undefined;
+}
+
+interface LinearIdentityData {
+  viewer?: {id?: unknown} | null;
+  organization?: {id?: unknown; name?: unknown; urlKey?: unknown} | null;
+}
+
+interface MapLinearErrorOptions {
+  classifyHttp4xx?(status: number): 'access-denied' | 'malformed-provider-response';
+}
+
+export function createLinearApiClient(): LinearApiClient {
+  return {
+    async exchangeAuthorizationCode(input) {
+      const body = await mapLinearError('exchange-authorization-code', () =>
+        ky
+          .post(LINEAR_OAUTH_TOKEN_URL, {
+            body: new URLSearchParams({
+              grant_type: 'authorization_code',
+              client_id: config.LINEAR_OAUTH_CLIENT_ID,
+              client_secret: config.LINEAR_OAUTH_CLIENT_SECRET,
+              code: input.code,
+              redirect_uri: config.LINEAR_OAUTH_REDIRECT_URL,
+            }),
+            timeout: LINEAR_API_TIMEOUT_MS,
+          })
+          .json<LinearTokenResponse>(),
+      );
+
+      return parseTokenResponse(body);
+    },
+
+    async refreshAccessToken(input) {
+      const body = await mapLinearError('refresh-access-token', () =>
+        ky
+          .post(LINEAR_OAUTH_TOKEN_URL, {
+            body: new URLSearchParams({
+              grant_type: 'refresh_token',
+              client_id: config.LINEAR_OAUTH_CLIENT_ID,
+              client_secret: config.LINEAR_OAUTH_CLIENT_SECRET,
+              refresh_token: input.refreshToken,
+            }),
+            timeout: LINEAR_API_TIMEOUT_MS,
+          })
+          .json<LinearTokenResponse>(),
+      );
+
+      return parseTokenResponse(body);
+    },
+
+    async revokeToken(input) {
+      await mapLinearError('revoke-token', async () => {
+        await ky.post(LINEAR_OAUTH_REVOKE_URL, {
+          body: new URLSearchParams({
+            client_id: config.LINEAR_OAUTH_CLIENT_ID,
+            client_secret: config.LINEAR_OAUTH_CLIENT_SECRET,
+            token: input.token,
+            token_type_hint: input.tokenTypeHint,
+          }),
+          timeout: LINEAR_API_TIMEOUT_MS,
+        });
+      });
+    },
+
+    async getIdentity(input) {
+      const body = await mapLinearError(
+        'get-identity',
+        () =>
+          ky
+            .post(LINEAR_GRAPHQL_URL, {
+              headers: {authorization: `Bearer ${input.accessToken}`},
+              json: {query: IDENTITY_QUERY},
+              timeout: LINEAR_API_TIMEOUT_MS,
+            })
+            .json<LinearGraphqlResponse<LinearIdentityData>>(),
+        {classifyHttp4xx: classifyGraphqlHttp4xx},
+      );
+      const data = graphqlData('get-identity', body);
+      const appUserId = data.viewer?.id;
+      const organizationId = data.organization?.id;
+      const organizationName = data.organization?.name;
+      const organizationUrlKey = data.organization?.urlKey;
+
+      if (
+        typeof appUserId !== 'string' ||
+        typeof organizationId !== 'string' ||
+        typeof organizationName !== 'string' ||
+        typeof organizationUrlKey !== 'string'
+      ) {
+        throw new LinearIntegrationProviderError(
+          'malformed-provider-response',
+          'Linear identity response did not include the app user and organization',
+        );
+      }
+
+      return {appUserId, organizationId, organizationName, organizationUrlKey};
+    },
+  };
+}
+
+function parseTokenResponse(body: LinearTokenResponse): LinearAuthorization {
+  if (typeof body.access_token !== 'string' || body.access_token.length === 0) {
+    throw new LinearIntegrationProviderError(
+      'malformed-provider-response',
+      'Linear authorization response did not include an access token',
+    );
+  }
+
+  const scopes = parseScopes(body.scope);
+  const expiresAt = parseExpiresAt(body.expires_in);
+  const refreshToken = typeof body.refresh_token === 'string' ? body.refresh_token : undefined;
+  return {accessToken: body.access_token, refreshToken, expiresAt, scopes};
+}
+
+function parseScopes(scope: unknown): string[] {
+  if (typeof scope === 'string') {
+    return scope
+      .split(SCOPE_SEPARATOR_RE)
+      .map((value) => value.trim())
+      .filter(Boolean);
+  }
+  if (Array.isArray(scope) && scope.every((value) => typeof value === 'string')) return scope;
+  if (scope === undefined) return [];
+  throw new LinearIntegrationProviderError(
+    'malformed-provider-response',
+    'Linear authorization response included malformed scopes',
+  );
+}
+
+function parseExpiresAt(expiresIn: unknown): Date | undefined {
+  if (expiresIn === undefined) return undefined;
+  if (typeof expiresIn !== 'number' || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+    throw new LinearIntegrationProviderError(
+      'malformed-provider-response',
+      'Linear authorization response included a malformed expiry',
+    );
+  }
+  return new Date(Date.now() + expiresIn * 1000);
+}
+
+function graphqlData<Data>(operation: string, body: LinearGraphqlResponse<Data>): Data {
+  if (hasGraphqlErrors(body)) {
+    const reason = hasAuthGraphqlError(body.errors)
+      ? 'access-denied'
+      : 'malformed-provider-response';
+    logger().warn({operation}, 'Linear GraphQL request returned errors');
+    throw new LinearIntegrationProviderError(reason, 'Linear GraphQL request failed');
+  }
+  if (!body.data) {
+    throw new LinearIntegrationProviderError(
+      'malformed-provider-response',
+      'Linear GraphQL response did not include data',
+    );
+  }
+  return body.data;
+}
+
+function hasGraphqlErrors(body: LinearGraphqlResponse<unknown>): boolean {
+  return Array.isArray(body.errors) && body.errors.length > 0;
+}
+
+function hasAuthGraphqlError(errors: LinearGraphqlError[] | undefined): boolean {
+  return (
+    errors?.some((error) => {
+      const type = error.extensions?.type;
+      return (
+        typeof type === 'string' && ['authentication', 'authorization'].includes(type.toLowerCase())
+      );
+    }) ?? false
+  );
+}
+
+async function mapLinearError<T>(
+  operation: string,
+  request: () => Promise<T>,
+  options: MapLinearErrorOptions = {},
+): Promise<T> {
+  try {
+    return await request();
+  } catch (error) {
+    if (error instanceof LinearIntegrationProviderError) throw error;
+    if (error instanceof HTTPError) {
+      const {status, statusText, headers} = error.response;
+      logger().warn({operation, status, statusText}, 'Linear API request rejected');
+      if (status === 429) {
+        throw new LinearIntegrationProviderError(
+          'rate-limited',
+          'Linear request was rate limited',
+          retryAfterSeconds(headers),
+        );
+      }
+      if (status >= 500) {
+        throw new LinearIntegrationProviderError('provider-unavailable', 'Linear request failed');
+      }
+      const reason = options.classifyHttp4xx?.(status) ?? 'access-denied';
+      throw new LinearIntegrationProviderError(reason, 'Linear request was rejected');
+    }
+    if (error instanceof TimeoutError) {
+      logger().warn({operation}, 'Linear API request timed out');
+      throw new LinearIntegrationProviderError('timeout', 'Linear request timed out');
+    }
+    logger().warn(
+      {operation, errName: error instanceof Error ? error.name : typeof error},
+      'Linear API request failed',
+    );
+    throw new LinearIntegrationProviderError('provider-unavailable', 'Linear request failed');
+  }
+}
+
+function classifyGraphqlHttp4xx(status: number): 'access-denied' | 'malformed-provider-response' {
+  return status === 401 || status === 403 ? 'access-denied' : 'malformed-provider-response';
+}
+
+function retryAfterSeconds(headers: Headers): number | undefined {
+  const retryAfter = headers.get('retry-after');
+  if (!retryAfter) return undefined;
+  const parsed = Number.parseInt(retryAfter, 10);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}

package/src/config.test.ts

@@ -0,0 +1,34 @@
+const linearEnvNames = [
+  'LINEAR_OAUTH_CLIENT_ID',
+  'LINEAR_OAUTH_CLIENT_SECRET',
+  'LINEAR_WEBHOOK_SIGNING_SECRET',
+  'LINEAR_OAUTH_REDIRECT_URL',
+] as const;
+
+describe('linear config', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it('exports validated Linear config from the package root', async () => {
+    vi.stubEnv('LINEAR_MCP_ENDPOINT', undefined);
+    vi.resetModules();
+
+    const {config} = await import('#index.js');
+
+    for (const name of linearEnvNames) {
+      expect(config[name]).toBe(process.env[name]);
+    }
+    expect(config.LINEAR_MCP_ENDPOINT).toBe('https://mcp.linear.app/mcp');
+  });
+
+  it('accepts a compatible Linear MCP endpoint override', async () => {
+    vi.stubEnv('LINEAR_MCP_ENDPOINT', 'https://linear-mcp.example.test/mcp');
+    vi.resetModules();
+
+    const {config} = await import('#index.js');
+
+    expect(config.LINEAR_MCP_ENDPOINT).toBe('https://linear-mcp.example.test/mcp');
+  });
+});

package/src/config.ts

@@ -0,0 +1,22 @@
+import {createConfig, str, url} from '@shipfox/config';
+
+const linearConfigSchema = {
+  LINEAR_OAUTH_CLIENT_ID: str({
+    desc: 'OAuth client ID of the Linear app, used to start and complete the Linear connect flow. Required.',
+  }),
+  LINEAR_OAUTH_CLIENT_SECRET: str({
+    desc: 'OAuth client secret of the Linear app, used to exchange authorization codes for workspace tokens. Required.',
+  }),
+  LINEAR_WEBHOOK_SIGNING_SECRET: str({
+    desc: 'Secret used to verify incoming Linear webhooks. Must match the signing secret configured on the Linear app. Required.',
+  }),
+  LINEAR_OAUTH_REDIRECT_URL: url({
+    desc: 'Public client callback URL Linear redirects to after OAuth authorization, such as https://shipfox.example.com/integrations/linear/callback. Required.',
+  }),
+  LINEAR_MCP_ENDPOINT: url({
+    desc: 'Streamable HTTP endpoint used for Linear MCP tool calls. Set this only when routing Linear tools through a compatible proxy or test server.',
+    default: 'https://mcp.linear.app/mcp',
+  }),
+};
+
+export const config = createConfig(linearConfigSchema);

package/src/connection-external-url.test.ts

@@ -0,0 +1,64 @@
+import type {LinearInstallation} from '#db/installations.js';
+import {createLinearIntegrationProvider} from '#index.js';
+
+function installation(overrides: Partial<LinearInstallation> = {}): LinearInstallation {
+  return {
+    id: crypto.randomUUID(),
+    connectionId: crypto.randomUUID(),
+    organizationId: 'org-1',
+    organizationUrlKey: 'acme',
+    appUserId: 'app-user-1',
+    scopes: ['read', 'write'],
+    tokenExpiresAt: null,
+    status: 'installed',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+describe('linear connectionExternalUrl', () => {
+  it('resolves the organization settings URL from the installation row', async () => {
+    const connectionId = crypto.randomUUID();
+    const provider = createLinearIntegrationProvider({
+      getLinearInstallationByConnectionId: () =>
+        Promise.resolve(installation({connectionId, organizationUrlKey: 'acme'})),
+    });
+
+    const url = await provider.connectionExternalUrl({id: connectionId});
+
+    expect(url).toBe('https://linear.app/acme/settings');
+  });
+
+  it('URL-encodes the organization URL key', async () => {
+    const provider = createLinearIntegrationProvider({
+      getLinearInstallationByConnectionId: () =>
+        Promise.resolve(installation({organizationUrlKey: 'a/b c'})),
+    });
+
+    const url = await provider.connectionExternalUrl({id: crypto.randomUUID()});
+
+    expect(url).toBe('https://linear.app/a%2Fb%20c/settings');
+  });
+
+  it('returns undefined when the installation row is missing', async () => {
+    const provider = createLinearIntegrationProvider({
+      getLinearInstallationByConnectionId: () => Promise.resolve(undefined),
+    });
+
+    const url = await provider.connectionExternalUrl({id: crypto.randomUUID()});
+
+    expect(url).toBeUndefined();
+  });
+
+  it('returns undefined when the organization URL key is absent', async () => {
+    const provider = createLinearIntegrationProvider({
+      getLinearInstallationByConnectionId: () =>
+        Promise.resolve(installation({organizationUrlKey: ''})),
+    });
+
+    const url = await provider.connectionExternalUrl({id: crypto.randomUUID()});
+
+    expect(url).toBeUndefined();
+  });
+});

package/src/core/agent-tools-provider.test.ts

@@ -0,0 +1,245 @@
+import {createServer, type IncomingMessage, type ServerResponse} from 'node:http';
+import type {CallToolResult} from '@modelcontextprotocol/sdk/types.js';
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {linearAgentToolCatalog, linearAgentToolSelectionCatalog} from '#core/agent-tools.js';
+import {LinearAgentToolsProvider} from '#core/agent-tools-provider.js';
+import {LinearAccessTokenMissingError} from '#core/errors.js';
+
+function linearConnection(
+  overrides: Partial<IntegrationConnection<'linear'>> = {},
+): IntegrationConnection<'linear'> {
+  const now = new Date();
+  return {
+    id: 'linear-connection-1',
+    workspaceId: 'workspace-1',
+    provider: 'linear',
+    externalAccountId: 'linear-org-1',
+    slug: 'linear-main',
+    displayName: 'Linear',
+    lifecycleStatus: 'active',
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+describe('LinearAgentToolsProvider', () => {
+  it('returns the Linear agent tools catalogs', () => {
+    const provider = new LinearAgentToolsProvider({
+      tokenStore: {getAccessToken: async () => 'linear-token'},
+    });
+
+    expect(provider.catalog()).toBe(linearAgentToolCatalog);
+    expect(provider.selectionCatalog()).toBe(linearAgentToolSelectionCatalog);
+  });
+
+  it('reads the stored token for the connection id before opening the MCP client', async () => {
+    const getAccessToken = vi.fn().mockResolvedValue('linear-token');
+    const createClient = vi.fn().mockResolvedValue({
+      callTool: vi.fn().mockResolvedValue({content: []}),
+      close: vi.fn().mockResolvedValue(undefined),
+    });
+    const provider = new LinearAgentToolsProvider({
+      tokenStore: {getAccessToken},
+      createClient,
+    });
+
+    await provider.openSession({
+      connection: linearConnection({id: 'linear-connection-7'}),
+      tools: [],
+      scope: {provider: 'linear'},
+    });
+
+    expect(getAccessToken).toHaveBeenCalledWith({connectionId: 'linear-connection-7'});
+    expect(createClient).toHaveBeenCalledWith({
+      endpoint: new URL('https://mcp.linear.app/mcp'),
+      accessToken: 'linear-token',
+    });
+  });
+
+  it('sends bearer auth to the remote Streamable HTTP MCP server', async () => {
+    const authorizations: (string | undefined)[] = [];
+    const server = createServer((request, response) => {
+      authorizations.push(request.headers.authorization);
+      handleMcpRequest(request, response);
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string') throw new Error('Expected TCP server address');
+    const provider = new LinearAgentToolsProvider({
+      tokenStore: {getAccessToken: async () => 'linear-token'},
+      endpoint: new URL(`http://127.0.0.1:${address.port}/mcp`),
+    });
+
+    try {
+      const session = await provider.openSession({
+        connection: linearConnection(),
+        tools: [],
+        scope: {provider: 'linear'},
+      });
+      const result = await session.call({toolId: 'get_issue', arguments: {id: 'ENG-875'}});
+      await session.close?.();
+
+      expect(result.structuredContent).toEqual({tool: 'get_issue'});
+      expect(authorizations.every((authorization) => authorization === 'Bearer linear-token')).toBe(
+        true,
+      );
+    } finally {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+      });
+    }
+  });
+
+  it('proxies read and write tool calls through the MCP client with the configured timeout', async () => {
+    const callTool = vi
+      .fn()
+      .mockResolvedValueOnce({
+        content: [{type: 'text', text: 'issue'}],
+        structuredContent: {id: 'ENG-875'},
+      } satisfies CallToolResult)
+      .mockResolvedValueOnce({
+        content: [{type: 'text', text: 'comment saved'}],
+        structuredContent: {id: 'comment-1'},
+      } satisfies CallToolResult);
+    const close = vi.fn().mockResolvedValue(undefined);
+    const provider = new LinearAgentToolsProvider({
+      tokenStore: {getAccessToken: async () => 'linear-token'},
+      callTimeoutMs: 1234,
+      createClient: async () => ({callTool, close}),
+    });
+    const session = await provider.openSession({
+      connection: linearConnection(),
+      tools: [],
+      scope: {provider: 'linear'},
+    });
+
+    const readResult = await session.call({
+      toolId: 'get_issue',
+      arguments: {id: 'ENG-875'},
+    });
+    const writeResult = await session.call({
+      toolId: 'save_comment',
+      arguments: {issueId: 'ENG-875', body: 'Looks good'},
+    });
+    await session.close?.();
+
+    expect(readResult.structuredContent).toEqual({id: 'ENG-875'});
+    expect(writeResult.structuredContent).toEqual({id: 'comment-1'});
+    expect(callTool).toHaveBeenNthCalledWith(
+      1,
+      {toolId: 'get_issue', arguments: {id: 'ENG-875'}},
+      1234,
+    );
+    expect(callTool).toHaveBeenNthCalledWith(
+      2,
+      {toolId: 'save_comment', arguments: {issueId: 'ENG-875', body: 'Looks good'}},
+      1234,
+    );
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not open an MCP client when the Linear token is missing', async () => {
+    const createClient = vi.fn();
+    const provider = new LinearAgentToolsProvider({
+      tokenStore: {
+        getAccessToken: () =>
+          Promise.reject(new LinearAccessTokenMissingError('linear-connection-1')),
+      },
+      createClient,
+    });
+
+    const result = provider.openSession({
+      connection: linearConnection(),
+      tools: [],
+      scope: {provider: 'linear'},
+    });
+
+    await expect(result).rejects.toBeInstanceOf(LinearAccessTokenMissingError);
+    expect(createClient).not.toHaveBeenCalled();
+  });
+
+  it('propagates remote provider errors and still exposes close for cleanup', async () => {
+    const remoteError = new Error('remote MCP rejected the request');
+    const close = vi.fn().mockResolvedValue(undefined);
+    const provider = new LinearAgentToolsProvider({
+      tokenStore: {getAccessToken: async () => 'linear-token'},
+      createClient: async () => ({
+        callTool: () => Promise.reject(remoteError),
+        close,
+      }),
+    });
+    const session = await provider.openSession({
+      connection: linearConnection(),
+      tools: [],
+      scope: {provider: 'linear'},
+    });
+
+    const result = session.call({toolId: 'get_issue', arguments: {id: 'ENG-875'}});
+    await session.close?.();
+
+    await expect(result).rejects.toBe(remoteError);
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+});
+
+function handleMcpRequest(request: IncomingMessage, response: ServerResponse): void {
+  if (request.method !== 'POST') {
+    response.writeHead(405).end();
+    return;
+  }
+
+  let body = '';
+  request.setEncoding('utf8');
+  request.on('data', (chunk) => {
+    body += chunk;
+  });
+  request.on('end', () => {
+    const message = JSON.parse(body) as {
+      id?: string | number;
+      method?: string;
+      params?: {name?: string};
+    };
+
+    if (message.method === 'notifications/initialized') {
+      response.writeHead(202).end();
+      return;
+    }
+
+    if (message.method === 'initialize') {
+      writeJson(response, {
+        jsonrpc: '2.0',
+        id: message.id,
+        result: {
+          protocolVersion: '2025-03-26',
+          capabilities: {tools: {}},
+          serverInfo: {name: 'mock-linear-mcp', version: '0.0.0'},
+        },
+      });
+      return;
+    }
+
+    if (message.method === 'tools/call') {
+      writeJson(response, {
+        jsonrpc: '2.0',
+        id: message.id,
+        result: {
+          content: [{type: 'text', text: 'ok'}],
+          structuredContent: {tool: message.params?.name},
+        },
+      });
+      return;
+    }
+
+    writeJson(response, {
+      jsonrpc: '2.0',
+      id: message.id,
+      error: {code: -32601, message: 'Method not found'},
+    });
+  });
+}
+
+function writeJson(response: ServerResponse, body: unknown): void {
+  response.writeHead(200, {'content-type': 'application/json'});
+  response.end(JSON.stringify(body));
+}