Linear

Connect your Linear organization to Squid to query and update issues

（Linear組織をSquidに接続して、課題のクエリや更新を行います）

Creating a Linear personal API key

（Linear個人APIキーの作成）

Requests to the Linear GraphQL API require an Authorization header. You can authorize your requests using OAuth2 access tokens or personal API keys. To learn more, view the Linear API documentation.
Linear GraphQL APIへのリクエストにはAuthorizationヘッダーが必要です。リクエストはOAuth2アクセストークンまたは個人APIキーを用いて認証できます。詳細はview the Linear API documentationをご参照ください。

The following instructions use a personal API key. However, the same capabilities could be achieved by creating an OAuth2 access token. Using the personal API key enables you to use Squid's injection capability to automatically add the API key to all requests.
以下の手順では個人APIキーを使用しますが、同様の機能はOAuth2アクセストークンを作成することで実現可能です。個人APIキーを使用することで、Squidのインジェクション機能を利用して、すべてのリクエストに自動的にAPIキーを追加できます。

Adding the integration

（統合の追加）

1. Navigate to the Integrations tab in the Squid Console.

   1. Squid Console の Integrations タブに移動します。

2. Click Available Integrations.
   2. Available Integrations をクリックします。

3. Find the GraphQL integration, and select Add Integration.
   3. GraphQL の統合を見つけ、Add Integration を選択します。

4. Provide the following details:
   4. 以下の詳細を入力します:

   Integration ID: A string of your choice that uniquely identifies the integration in your code.
   Integration ID: コード内で統合を一意に識別するための任意の文字列。

   Base URL: https://api.linear.app/graphql

   Inject Request Headers: Toggle on.
   Inject Request Headers: onにトグルします。

   Field name: Authorization
   Location: Header

   Secret Toggle on. Create a new secret and put your Linear personal API key as the value. Secrets are stored securely in Squid. For more information on Squid Secrets, view the Secrets documentation.
   Secret のトグルを on にします。新しいsecretを作成し、値としてLinear個人APIキーを入力してください。SecretsはSquid内に安全に保存されます。Squid Secretsの詳細については、view the Secrets documentationを参照してください。

5. Save your newly created secret.
   5. 作成したsecretを保存します。

6. Click Add field to save injection.
   6. Add field をクリックしてインジェクションを保存します。

7. Click Test Connection to test your connection to the API. If the connection fails, verify the value of your endpoint and try re-entering the value of your secret in the Secrets tab of the console.
   7. Test Connection をクリックしてAPIへの接続をテストします。接続に失敗した場合は、endpointの値を確認し、consoleのSecretsタブでsecretの値を再入力してみてください。

8. When the connection is successful, click Add Integration.
   8. 接続が成功したら、Add Integration をクリックします。

Using the integration

（統合の使用方法）

1. Add the following imports to your application. If running the GraphQLClient from the Squid backend, you don't need to import Squid. Instead, you can access a provided Squid instance using this.squid.
   1. 以下のimportをアプリケーションに追加します。Squid backendからGraphQLClientを実行する場合、Squidをimportする必要はなく、代わりにthis.squidを使用して提供されたSquidのインスタンスにアクセスできます。

import { Squid } from '@squidcloud/client';
import { GraphQLClient } from '@squidcloud/graphql';

2. Create a GraphQL client, passing your Squid instance and the ID of your integration:
   2. Squidのインスタンスと統合のIDを渡してGraphQL clientを作成します:

const graphQLClient = new GraphQLClient(squid, 'INTEGRATION_ID');

3. To perform a query, use the GraphQLClient's query method, passing an object containing your query and any variables:
   3. クエリを実行するには、GraphQLClientのqueryメソッドを使用し、クエリと変数を含むオブジェクトを渡します:

const graphQLClient = new GraphQLClient(squid, 'INTEGRATION_ID');
const query = `
    query(id: String!) {
        issue(id: $id) {
            id
            title
            description
            url
        }
    }
`;
const variables = {
  id: 'some_id',
};

const result = await graphQLClient.query({
  query: query,
  variables: variables,
});

4. To run a mutation, use the GraphQLClient's mutate method, passing your query and any variables:
   4. ミューテーションを実行するには、GraphQLClientのmutateメソッドを使用し、クエリと変数を渡します:

const graphQLClient = new GraphQLClient(squid, 'INTEGRATION_ID');

const graphQlRequest = `
    mutation ($title: String!, $description: String!, $teamId: String!, $stateId: String!) {
    issueCreate(
        input: {
        title: $title,
        description: $description,
        teamId: $teamId,
        stateId: $stateId
        }
    ) {
        success
        issue {
        id
        title
        description
        }
    }
    }
`;
const variables = {
  title: 'Example Title',
  description: 'Example description.',
  teamId: 'someTeamId',
  stateId: 'someStateId',
};

const result = await graphQLClient.mutate({
  query: graphQlRequest,
  variables: variables,
});

Using your integration with an AI agent

（AIエージェントとの統合の使用方法）

There are two main ways you can use your Linear integration with an AI agent:
Linear統合をAIエージェントで使用する主な方法は、次の2つです:

1. Use an AI function to get the variables you need, and pass them to a specific query you want to perform.

   1. 必要な変数を取得するためにAI functionを使用し、それらを実行したい特定のクエリに渡します。

2. Provide your AI agent with Linear's GraphQL schema and allow the agent to create the queries for you.
   2. AIエージェントにLinearのGraphQLスキーマを提供し、エージェントにクエリの作成を任せます。

Using Linear in an AI function

（AI functionでLinearを使用する）

1. In your Squid backend, implement an AI function that performs the desired action. AI functions allow an agent to run specified TypeScript functions based on its understanding of prompts.

   1. Squid backendで、目的のアクションを実行するAI functionを実装します。AI functionsは、プロンプトの内容を理解した上で、エージェントが指定されたTypeScript関数を実行できるようにします。

   When writing an AI function, attach the @aiFunction decorator to your function, and include a description of when the AI agent should call the function and what parameters it needs to pass. For more information on AI functions, view the AI functions documentation.
   AI function作成時には、関数に@aiFunctionデコレーターを付与し、エージェントがその関数を呼び出すタイミングや渡すべきパラメータについて説明を記載してください。詳細は、view the AI functions documentationを参照してください。

   The following example showcases a function that queries Linear issues using a keyword filter:
   以下の例は、キーワードフィルターを使用してLinearの課題をクエリする関数の例です:

Backend code

import { SquidService } from '@squidcloud/backend';

export class ExampleService extends SquidService {
  @aiFunction(
    'Call this function when someone asks to find issues based on a keyword.',
    [
      {
        name: 'filter',
        description: 'The keyword or words to search for',
        required: true,
        type: 'string',
      },
    ],
  )
  async searchForIssue(filter) {
    const { filter } = data;
    const query = `
        query(searchTerm: String!) {
            issues(filter: { description: { containsIgnoreCase: $searchTerm } }) {
                nodes {
                    id
                    title
                    description
                    url
                }
            }
        }
    `;
    const variables = {
      searchTerm: filter,
    }

    const result = await graphQLClient.query({
      query: query,
      variables: variables,
    });
    return result;
  }
}

2. To use the function, create an AI agent and include the function as an option in calls to the agent.
   2. この関数を使用するには、AIエージェントを作成し、エージェントへの呼び出し時にその関数をオプションとして含めます。

   The following example will call the searchForIssue function based on the provided prompt, and will search the descriptions of Linear issues for 'credit':
   以下の例は、提供されたプロンプトに基づきsearchForIssue関数を呼び出し、Linearの課題の説明を 'credit' で検索します:

Backend code

const response = await this.squid
  .ai()
  .agent('AGENT_ID')
  .ask('Which linear issues mention credit?', {
    functions: ['searchForIssue'],
  });

Performing queries on the fly

（動的なクエリ実行）

If you don't know what queries the client might need to run, you can allow an AI agent to run queries on your behalf. As a prompt, provide a description of the query to perform, and the AI agent can create the query that you then pass to the GraphQLClient.
クライアントが実行する可能性のあるクエリが不明な場合、AIエージェントに代わってクエリを実行させることができます。プロンプトとして実行すべきクエリの説明を提供すると、AIエージェントがそのクエリを作成し、あなたはそれをGraphQLClientに渡すことになります。

1. Provide your AI agent with the Linear GraphQL schema as context. In the Squid Console, navigate to your AI agent, and then upload the latest schema. You can download the schema from the Linear documentation.

   1. AIエージェントに文脈としてLinear GraphQLスキーマを提供します。Squid Consoleで対象のAIエージェントに移動し、最新のスキーマをアップロードしてください。スキーマはLinear documentationからダウンロードできます。

2. For instructions, inform the agent how it should interpret the client prompt.
   2. 指示として、エージェントにクライアントプロンプトの解釈方法を伝えます。

   The following example showcases one option for generating queries:
   以下の例は、クエリ生成のための1つのオプションを示しています:

Using Linear's GraphQL API reference and the Squid GraphQLClient reference, generate the correct query to pass to the Squid GraphQLClient, and pass it to the callLinearAPI function. Always include `url` as a query parameter.

!! Important: Use Linear's GraphQL API reference as context.

!!Important: Do not pass issue IDs or other data points that aren't provided in the prompt.

When filtering with `contains`, always use `containsIgnoreCase`.

If querying for search terms in an issue, only search the description.

Example response format to pass to the function:

query {
  issue(id: "DEV-184") {
    id
    title
    description
    url
  }
}

Notice that these instructions include "!!Important" to highlight key points the agent needs to adhere to. It also specifies how the agent should produce the queries. For example, "If querying for search terms in an issue, only search the description." You can modify these instructions to suit your specific querying needs.
これらの指示には、エージェントが守るべき重要なポイントを示すために「!!Important」が含まれています。また、エージェントがどのようにクエリを生成すべきかが指定されています。例えば、「課題内の検索用語でクエリを実行する場合は、descriptionのみを検索してください」となっています。これらの指示は、具体的なクエリ要件に合わせて変更できます。

3. In the Squid backend, create the AI function that will perform the query produced by the AI agent.
   3. Squid backendで、AIエージェントが生成したクエリを実行するAI functionを作成します.

   The following AI function takes the query from the AI agent as a parameter, and then performs the query using the GraphQLClient.
   以下のAI functionは、AIエージェントからのクエリをパラメータとして受け取り、その後GraphQLClientを使用してクエリを実行します.

Backend code

import { SquidService } from '@squidcloud/backend';

export class ExampleService extends SquidService {
  @aiFunction(
    'call this function when someone asks to query their Linear issues, including querying open issues, updates, cycles, etc.',
    [
      {
        name: 'graphQLQuery',
        description: 'The GraphQL query for the Linear GraphQL API',
        required: true,
        type: 'string',
      },
    ],
  )
  async callLinearAPI(data: { graphQLQuery: string }) {
    const { graphQLQuery } = data;
    // Remove markdown
    const query = graphQLQuery.replace(/```graphql|`/g, '');

    const graphQLClient = new GraphQLClient(
      this.squid,
      'LINEAR_API_INTEGRATION_ID',
    );

    const result = await graphQLClient.query({
      query: query,
    });
  }
}