tessl/npm-linear--sdk

The Linear Client SDK for interacting with the Linear GraphQL API

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Linear SDK

Name: tessl/npm-linear--sdk
Author: tessl

Linear SDK is the official TypeScript/JavaScript client library for the Linear API, providing comprehensive access to Linear's project management platform. It offers a high-level client interface with authentication, error handling, type safety, and webhook utilities for building integrations and automations with Linear.

Package Information

Package Name: @linear/sdk
Package Type: npm
Language: TypeScript
Installation: npm install @linear/sdk

Core Imports

import { LinearClient } from "@linear/sdk";

For CommonJS:

const { LinearClient } = require("@linear/sdk");

For webhooks:

import { LinearWebhookClient } from "@linear/sdk/webhooks";

Deprecated webhook import (still available but not recommended):

import { LinearWebhooks } from "@linear/sdk"; // @deprecated Use LinearWebhookClient from "@linear/sdk/webhooks"

Basic Usage

import { LinearClient } from "@linear/sdk";

// Initialize client with API key
const client = new LinearClient({
  apiKey: "YOUR_API_KEY"
});

// Fetch issues
const issues = await client.issues({
  first: 10,
  filter: {
    team: {
      key: {
        eq: "ENG"
      }
    }
  }
});

// Create an issue
const newIssue = await client.createIssue({
  teamId: "team-id",
  title: "Bug: Fix login issue",
  description: "Users unable to login"
});

// Access the created issue
console.log(newIssue.issue?.title);

Architecture

The Linear SDK is built around several key components:

LinearClient: Main client class providing authenticated access to the Linear GraphQL API
Generated SDK: Type-safe operations generated from Linear's GraphQL schema (300+ operations)
GraphQL Layer: Low-level GraphQL client handling requests and responses
Error System: Comprehensive error types with Linear-specific error handling and rate limiting
Webhook System: Secure webhook processing with signature verification and event handling
Type System: Complete TypeScript definitions for all Linear API entities and operations
Pagination Support: Relay-spec compliant pagination with helper methods

Capabilities

Core Client Operations

Main Linear API client providing authenticated access to all Linear GraphQL operations including queries and mutations.

class LinearClient extends LinearSdk {
  constructor(options: LinearClientOptions);

  // Key properties
  options: LinearClientParsedOptions;
  client: LinearGraphQLClient;
}

interface LinearClientOptions extends RequestInit {
  apiKey?: string;
  accessToken?: string;
  apiUrl?: string;
}

Core Client Operations

Issue Management

Comprehensive issue operations including creation, updates, queries, and relationship management.

// Query operations
issue(id: string): LinearFetch<Issue>;
issues(variables?: IssuesQueryVariables): LinearFetch<IssueConnection>;

// Mutation operations
createIssue(input: IssueCreateInput): LinearFetch<IssuePayload>;
updateIssue(id: string, input: IssueUpdateInput): LinearFetch<IssuePayload>;
deleteIssue(id: string): LinearFetch<DeletePayload>;

Issue Management

Project Management

Project operations for creating, managing, and tracking projects and initiatives.

// Query operations
project(id: string): LinearFetch<Project>;
projects(variables?: ProjectsQueryVariables): LinearFetch<ProjectConnection>;

// Mutation operations
createProject(input: ProjectCreateInput): LinearFetch<ProjectPayload>;
updateProject(id: string, input: ProjectUpdateInput): LinearFetch<ProjectPayload>;

Project Management

Team & User Management

Team and user operations for managing workspace members, teams, and permissions.

// Query operations
team(id: string): LinearFetch<Team>;
teams(variables?: TeamsQueryVariables): LinearFetch<TeamConnection>;
users(variables?: UsersQueryVariables): LinearFetch<UserConnection>;

// Mutation operations
createTeam(input: TeamCreateInput): LinearFetch<TeamPayload>;
updateTeam(id: string, input: TeamUpdateInput): LinearFetch<TeamPayload>;

Team & User Management

Workflow & Cycle Management

Development cycle and workflow state management for organizing work and tracking progress.

// Query operations
cycles(variables?: CyclesQueryVariables): LinearFetch<CycleConnection>;
workflowStates(variables?: WorkflowStatesQueryVariables): LinearFetch<WorkflowStateConnection>;

// Mutation operations
createCycle(input: CycleCreateInput): LinearFetch<CyclePayload>;
updateCycle(id: string, input: CycleUpdateInput): LinearFetch<CyclePayload>;

Workflow & Cycle Management

Comments & Attachments

Comment and attachment operations for collaboration and file management.

// Query operations
comments(variables?: CommentsQueryVariables): LinearFetch<CommentConnection>;
attachments(variables?: AttachmentsQueryVariables): LinearFetch<AttachmentConnection>;

// Mutation operations
createComment(input: CommentCreateInput): LinearFetch<CommentPayload>;
updateComment(id: string, input: CommentUpdateInput): LinearFetch<CommentPayload>;

Comments & Attachments

Error Handling

Comprehensive error handling with Linear-specific error types, rate limiting support, and structured error information.

class LinearError extends Error {
  type?: LinearErrorType;
  errors?: LinearGraphQLError[];
  query?: string;
  variables?: Record<string, unknown>;
  status?: number;
  data?: unknown;
}

enum LinearErrorType {
  FeatureNotAccessible = "FeatureNotAccessible",
  InvalidInput = "InvalidInput",
  Ratelimited = "Ratelimited",
  NetworkError = "NetworkError",
  AuthenticationError = "AuthenticationError",
  Forbidden = "Forbidden"
}

Error Handling

Webhook Processing

Secure webhook handling with signature verification, event parsing, and type-safe event handlers.

class LinearWebhookClient {
  constructor(secret: string);

  createHandler(): LinearWebhookHandler;
  verify(rawBody: Buffer, signature: string, timestamp?: number): boolean;
  parseData(rawBody: Buffer, signature: string, timestamp?: number): LinearWebhookPayload;
}

interface LinearWebhookHandler {
  (request: Request): Promise<Response>;
  (request: IncomingMessage, response: ServerResponse): Promise<void>;
  on<T extends LinearWebhookEventType>(eventType: T, handler: LinearWebhookEventHandler<Extract<LinearWebhookPayload, { type: T }>>): void;
  off<T extends LinearWebhookEventType>(eventType: T, handler: LinearWebhookEventHandler<Extract<LinearWebhookPayload, { type: T }>>): void;
}

Webhook Processing

Pagination & Connections

Relay-spec compliant pagination with automatic page fetching and helper utilities.

class Connection<Node> extends LinearConnection<Node> {
  pageInfo: PageInfo;
  nodes: Node[];

  fetchNext(): Promise<this>;
  fetchPrevious(): Promise<this>;
}

interface LinearConnectionVariables {
  after?: string | null;
  before?: string | null;
  first?: number | null;
  last?: number | null;
}

Pagination & Connections

Core Types

// Pagination and fetching
type LinearFetch<Response> = Promise<Response>;
type LinearRequest = <Response, Variables extends Record<string, unknown>>(
  doc: DocumentNode,
  variables?: Variables
) => Promise<Response>;

// Client configuration
interface LinearClientParsedOptions extends RequestInit {
  apiUrl: string;
}

// Response structures
interface LinearRawResponse<Data> {
  data?: Data;
  extensions?: unknown;
  headers?: Headers;
  status?: number;
  error?: string;
  errors?: LinearGraphQLErrorRaw[];
}

// GraphQL context
interface GraphQLRequestContext<Variables extends Record<string, unknown>> {
  query: string;
  variables?: Variables;
}

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 2 months ago
Describes: pkg:npm/@linear/sdk@59.1.x
Publish Source: CLI
Badge