@enrichlayer/el-linear 1.2.0

package/dist/utils/download-uploads.js

@@ -0,0 +1,88 @@
+import { mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { FileService } from "./file-service.js";
+const DOWNLOAD_DIR = join(tmpdir(), "el-linear-downloads");
+const UPLOAD_URL_REGEX = /https:\/\/uploads\.linear\.app\/[^\s)>\]"]+/g;
+function collectUploadUrls(text) {
+    const matches = text.match(UPLOAD_URL_REGEX);
+    return matches ? [...new Set(matches)] : [];
+}
+function replaceUrls(text, urlMap) {
+    let result = text;
+    for (const [remote, local] of urlMap) {
+        result = result.replaceAll(remote, local);
+    }
+    return result;
+}
+/**
+ * Downloads all uploads.linear.app URLs found in an issue's description
+ * and comments, replacing them with local file paths so Claude Code
+ * can read the images directly.
+ */
+export async function downloadLinearUploads(issue, apiToken) {
+    const allUrls = new Set();
+    if (issue.description) {
+        for (const url of collectUploadUrls(issue.description)) {
+            allUrls.add(url);
+        }
+    }
+    if (issue.comments) {
+        for (const comment of issue.comments) {
+            for (const url of collectUploadUrls(comment.body)) {
+                allUrls.add(url);
+            }
+        }
+    }
+    if (allUrls.size === 0) {
+        return issue;
+    }
+    await mkdir(DOWNLOAD_DIR, { recursive: true });
+    const fileService = new FileService(apiToken);
+    const urlMap = new Map();
+    await Promise.all([...allUrls].map(async (url) => {
+        const filename = extractUniqueFilename(url);
+        const localPath = join(DOWNLOAD_DIR, filename);
+        const result = await fileService.downloadFile(url, {
+            output: localPath,
+            overwrite: true,
+        });
+        if (result.success) {
+            urlMap.set(url, result.filePath);
+        }
+    }));
+    if (urlMap.size === 0) {
+        return issue;
+    }
+    const updated = { ...issue };
+    if (updated.description) {
+        updated.description = replaceUrls(updated.description, urlMap);
+    }
+    if (updated.comments) {
+        updated.comments = updated.comments.map((comment) => ({
+            ...comment,
+            body: replaceUrls(comment.body, urlMap),
+        }));
+    }
+    if (updated.embeds) {
+        updated.embeds = updated.embeds.map((embed) => {
+            const local = urlMap.get(embed.url);
+            return local ? { ...embed, url: local } : embed;
+        });
+    }
+    return updated;
+}
+function extractUniqueFilename(url) {
+    try {
+        const urlObj = new URL(url);
+        // Path like /workspace-id/uuid1/uuid2/filename.png — take last two parts for uniqueness
+        const parts = urlObj.pathname.split("/").filter(Boolean);
+        if (parts.length >= 2) {
+            return `${parts.at(-2).slice(0, 8)}-${parts.at(-1)}`;
+        }
+        return parts.at(-1) || "download";
+    }
+    catch {
+        return `download-${Date.now()}`;
+    }
+}

package/dist/utils/embed-parser.d.ts

@@ -0,0 +1,8 @@
+export interface Embed {
+    expiresAt: string;
+    label: string;
+    url: string;
+}
+export declare function extractEmbeds(content: string | null | undefined): Embed[];
+export declare function isLinearUploadUrl(url: string): boolean;
+export declare function extractFilenameFromUrl(url: string): string;

package/dist/utils/embed-parser.js

@@ -0,0 +1,54 @@
+function stripCodeContexts(content) {
+    let cleaned = content.replace(/\\`/g, "");
+    cleaned = cleaned.replace(/```[\s\S]*?```/g, "");
+    cleaned = cleaned.replace(/`[^`]+`/g, "");
+    return cleaned;
+}
+export function extractEmbeds(content) {
+    if (!content) {
+        return [];
+    }
+    const cleanedContent = stripCodeContexts(content);
+    const embeds = [];
+    const imageRegex = /!\[([^\]]*)\]\(([^)]+)\)/g;
+    const linkRegex = /(?<!!)\[([^\]]+)\]\(([^)]+)\)/g;
+    const expiresAt = new Date(Date.now() + 3600 * 1000).toISOString();
+    for (const match of cleanedContent.matchAll(imageRegex)) {
+        const label = match[1] || "file";
+        const url = match[2];
+        if (isLinearUploadUrl(url)) {
+            embeds.push({ label, url, expiresAt });
+        }
+    }
+    for (const match of cleanedContent.matchAll(linkRegex)) {
+        const label = match[1] || "file";
+        const url = match[2];
+        if (isLinearUploadUrl(url)) {
+            embeds.push({ label, url, expiresAt });
+        }
+    }
+    return embeds;
+}
+export function isLinearUploadUrl(url) {
+    if (!url) {
+        return false;
+    }
+    try {
+        const urlObj = new URL(url);
+        return urlObj.hostname === "uploads.linear.app";
+    }
+    catch {
+        return false;
+    }
+}
+export function extractFilenameFromUrl(url) {
+    try {
+        const urlObj = new URL(url);
+        const pathname = urlObj.pathname;
+        const parts = pathname.split("/");
+        return parts.at(-1) || "download";
+    }
+    catch {
+        return "download";
+    }
+}

package/dist/utils/error-messages.d.ts

@@ -0,0 +1,4 @@
+export declare function notFoundError(entityType: string, identifier: string, context?: string, hint?: string): Error;
+export declare function multipleMatchesError(entityType: string, identifier: string, matches: string[], disambiguation: string): Error;
+export declare function invalidParameterError(parameter: string, reason: string): Error;
+export declare function requiresParameterError(flag: string, requiredFlag: string): Error;

package/dist/utils/error-messages.js

@@ -0,0 +1,17 @@
+export function notFoundError(entityType, identifier, context, hint) {
+    const contextStr = context ? ` ${context}` : "";
+    const hintStr = hint ? ` ${hint}` : "";
+    return new Error(`${entityType} "${identifier}"${contextStr} not found.${hintStr}`);
+}
+export function multipleMatchesError(entityType, identifier, matches, disambiguation) {
+    const matchList = matches.join(", ");
+    return new Error(`Multiple ${entityType}s found matching "${identifier}". ` +
+        `Candidates: ${matchList}. ` +
+        `Please ${disambiguation}.`);
+}
+export function invalidParameterError(parameter, reason) {
+    return new Error(`Invalid ${parameter}: ${reason}`);
+}
+export function requiresParameterError(flag, requiredFlag) {
+    return new Error(`${flag} requires ${requiredFlag} to be specified`);
+}

package/dist/utils/file-service.d.ts

@@ -0,0 +1,13 @@
+import type { FileDownloadResult, FileUploadResult } from "../types/linear.js";
+export declare class FileService {
+    private readonly apiToken;
+    constructor(apiToken: string);
+    downloadFile(url: string, options?: {
+        output?: string;
+        overwrite?: boolean;
+    }): Promise<FileDownloadResult>;
+    uploadFile(filePath: string): Promise<FileUploadResult>;
+    private validateFileForUpload;
+    private requestUploadUrl;
+    private putFileToUrl;
+}

package/dist/utils/file-service.js

@@ -0,0 +1,239 @@
+import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname } from "node:path";
+import { extractFilenameFromUrl, isLinearUploadUrl } from "./embed-parser.js";
+const MAX_FILE_SIZE = 20 * 1024 * 1024;
+const MIME_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".ico": "image/x-icon",
+    ".pdf": "application/pdf",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xls": "application/vnd.ms-excel",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".txt": "text/plain",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".xml": "application/xml",
+    ".html": "text/html",
+    ".css": "text/css",
+    ".js": "application/javascript",
+    ".ts": "application/typescript",
+    ".md": "text/markdown",
+    ".zip": "application/zip",
+    ".tar": "application/x-tar",
+    ".gz": "application/gzip",
+    ".mp4": "video/mp4",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+};
+function getMimeType(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return MIME_TYPES[ext] || "application/octet-stream";
+}
+export class FileService {
+    apiToken;
+    constructor(apiToken) {
+        this.apiToken = apiToken;
+    }
+    async downloadFile(url, options = {}) {
+        if (!isLinearUploadUrl(url)) {
+            return {
+                success: false,
+                error: "URL must be from uploads.linear.app domain",
+            };
+        }
+        const outputPath = options.output || extractFilenameFromUrl(url);
+        if (!options.overwrite) {
+            try {
+                await access(outputPath);
+                return {
+                    success: false,
+                    error: `File already exists: ${outputPath}. Use --overwrite to replace.`,
+                };
+            }
+            catch {
+                // File doesn't exist, good
+            }
+        }
+        try {
+            const urlObj = new URL(url);
+            const isSignedUrl = urlObj.searchParams.has("signature");
+            const headers = {};
+            if (!isSignedUrl) {
+                headers.Authorization = this.apiToken;
+            }
+            const response = await fetch(url, { method: "GET", headers });
+            if (!response.ok) {
+                return {
+                    success: false,
+                    error: `HTTP ${response.status}: ${response.statusText}`,
+                    statusCode: response.status,
+                };
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            const buffer = Buffer.from(arrayBuffer);
+            const outputDir = dirname(outputPath);
+            if (outputDir !== ".") {
+                await mkdir(outputDir, { recursive: true });
+            }
+            await writeFile(outputPath, buffer);
+            return { success: true, filePath: outputPath };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async uploadFile(filePath) {
+        const filename = basename(filePath);
+        const validation = await this.validateFileForUpload(filePath);
+        if (!validation.ok) {
+            return validation.error;
+        }
+        const contentType = getMimeType(filePath);
+        try {
+            const uploadMeta = await this.requestUploadUrl(contentType, filename, validation.fileSize);
+            if (!uploadMeta.ok) {
+                return uploadMeta.error;
+            }
+            return await this.putFileToUrl(filePath, contentType, filename, uploadMeta);
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async validateFileForUpload(filePath) {
+        try {
+            await access(filePath);
+        }
+        catch {
+            return {
+                ok: false,
+                error: { success: false, error: `File not found: ${filePath}` },
+            };
+        }
+        try {
+            const fileStat = await stat(filePath);
+            if (fileStat.size > MAX_FILE_SIZE) {
+                const maxMB = MAX_FILE_SIZE / (1024 * 1024);
+                const actualMB = fileStat.size / (1024 * 1024);
+                return {
+                    ok: false,
+                    error: {
+                        success: false,
+                        error: `File too large: ${actualMB.toFixed(1)}MB exceeds limit of ${maxMB}MB`,
+                    },
+                };
+            }
+            return { ok: true, fileSize: fileStat.size };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: {
+                    success: false,
+                    error: `Cannot read file: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            };
+        }
+    }
+    async requestUploadUrl(contentType, filename, fileSize) {
+        const query = `
+      mutation FileUpload($contentType: String!, $filename: String!, $size: Int!) {
+        fileUpload(contentType: $contentType, filename: $filename, size: $size) {
+          success
+          uploadFile { uploadUrl assetUrl headers { key value } }
+        }
+      }
+    `;
+        const response = await fetch("https://api.linear.app/graphql", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: this.apiToken,
+            },
+            body: JSON.stringify({
+                query,
+                variables: { contentType, filename, size: fileSize },
+            }),
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                error: {
+                    success: false,
+                    error: `GraphQL request failed: HTTP ${response.status}`,
+                    statusCode: response.status,
+                },
+            };
+        }
+        const data = (await response.json());
+        if (data.errors) {
+            return {
+                ok: false,
+                error: {
+                    success: false,
+                    error: `Failed to request upload URL: ${data.errors[0]?.message || "GraphQL error"}`,
+                },
+            };
+        }
+        const fileUpload = data.data?.fileUpload;
+        if (!fileUpload?.success) {
+            return {
+                ok: false,
+                error: {
+                    success: false,
+                    error: "Failed to request upload URL: success=false",
+                },
+            };
+        }
+        const uploadFile = fileUpload.uploadFile;
+        if (!(uploadFile?.uploadUrl && uploadFile?.assetUrl)) {
+            return {
+                ok: false,
+                error: {
+                    success: false,
+                    error: "Missing uploadUrl or assetUrl in response",
+                },
+            };
+        }
+        return {
+            ok: true,
+            uploadUrl: uploadFile.uploadUrl,
+            assetUrl: uploadFile.assetUrl,
+            headers: uploadFile.headers || [],
+        };
+    }
+    async putFileToUrl(filePath, contentType, filename, meta) {
+        const fileBuffer = await readFile(filePath);
+        const putHeaders = { "Content-Type": contentType };
+        for (const header of meta.headers) {
+            putHeaders[header.key] = header.value;
+        }
+        const putResponse = await fetch(meta.uploadUrl, {
+            method: "PUT",
+            headers: putHeaders,
+            body: new Uint8Array(fileBuffer),
+        });
+        if (!putResponse.ok) {
+            return {
+                success: false,
+                error: `File upload failed: HTTP ${putResponse.status}`,
+                statusCode: putResponse.status,
+            };
+        }
+        return { success: true, assetUrl: meta.assetUrl, filename };
+    }
+}

package/dist/utils/gdoc-parser.d.ts

@@ -0,0 +1,45 @@
+interface GDocElement {
+    inlineObjectElement?: {
+        inlineObjectId: string;
+    };
+    textRun?: {
+        content: string;
+        textStyle?: {
+            bold?: boolean;
+            italic?: boolean;
+            link?: {
+                url?: string;
+            };
+        };
+    };
+}
+interface GDocParagraph {
+    bullet?: {
+        nestingLevel?: number;
+        listId?: string;
+    };
+    elements: GDocElement[];
+    paragraphStyle?: {
+        namedStyleType?: string;
+    };
+}
+interface GDocContent {
+    paragraph?: GDocParagraph;
+    table?: {
+        tableRows: Array<{
+            tableCells: Array<{
+                content: GDocContent[];
+            }>;
+        }>;
+    };
+}
+interface GDocBody {
+    content: GDocContent[];
+}
+interface GDocResponse {
+    body: GDocBody;
+    title?: string;
+}
+export declare function parseGoogleDoc(doc: GDocResponse): string;
+export declare function extractDocId(input: string): string;
+export {};

package/dist/utils/gdoc-parser.js

@@ -0,0 +1,107 @@
+const TRAILING_NEWLINE_RE = /\n$/;
+const GDOC_URL_RE = /\/document\/d\/([a-zA-Z0-9_-]+)/;
+function formatTextRun(element) {
+    const run = element.textRun;
+    if (!run?.content) {
+        return "";
+    }
+    let text = run.content;
+    const style = run.textStyle;
+    if (!style) {
+        return text;
+    }
+    // Don't wrap newlines in formatting
+    if (text.trim() === "") {
+        return text;
+    }
+    const trimmedEnd = text.endsWith("\n");
+    if (trimmedEnd) {
+        text = text.slice(0, -1);
+    }
+    if (style.link?.url) {
+        text = `[${text}](${style.link.url})`;
+    }
+    else if (style.bold && style.italic) {
+        text = `***${text}***`;
+    }
+    else if (style.bold) {
+        text = `**${text}**`;
+    }
+    else if (style.italic) {
+        text = `*${text}*`;
+    }
+    if (trimmedEnd) {
+        text += "\n";
+    }
+    return text;
+}
+function paragraphToMarkdown(para) {
+    const style = para.paragraphStyle?.namedStyleType || "NORMAL_TEXT";
+    let line = "";
+    for (const element of para.elements) {
+        line += formatTextRun(element);
+    }
+    // Handle bullet lists
+    if (para.bullet) {
+        const indent = "  ".repeat(para.bullet.nestingLevel || 0);
+        const content = line.replace(TRAILING_NEWLINE_RE, "");
+        return `${indent}- ${content}\n`;
+    }
+    // Handle headings
+    switch (style) {
+        case "HEADING_1":
+            return `# ${line}`;
+        case "HEADING_2":
+            return `## ${line}`;
+        case "HEADING_3":
+            return `### ${line}`;
+        case "HEADING_4":
+            return `#### ${line}`;
+        case "HEADING_5":
+            return `##### ${line}`;
+        case "HEADING_6":
+            return `###### ${line}`;
+        default:
+            return line;
+    }
+}
+export function parseGoogleDoc(doc) {
+    const body = doc.body?.content;
+    if (!body) {
+        return "";
+    }
+    const parts = [];
+    for (const block of body) {
+        if (block.paragraph) {
+            parts.push(paragraphToMarkdown(block.paragraph));
+        }
+        if (block.table) {
+            for (const row of block.table.tableRows) {
+                const cells = row.tableCells.map((cell) => {
+                    const cellText = cell.content
+                        .filter((c) => c.paragraph)
+                        .map((c) => {
+                        let text = "";
+                        for (const el of c.paragraph.elements) {
+                            text += formatTextRun(el);
+                        }
+                        return text.replace(TRAILING_NEWLINE_RE, "");
+                    })
+                        .join(" ");
+                    return cellText;
+                });
+                parts.push(`| ${cells.join(" | ")} |\n`);
+            }
+        }
+    }
+    return parts.join("");
+}
+export function extractDocId(input) {
+    // Full URL: https://docs.google.com/document/d/DOC_ID/...
+    const urlMatch = input.match(GDOC_URL_RE);
+    if (urlMatch) {
+        return urlMatch[1];
+    }
+    // Bare ID
+    return input;
+}

package/dist/utils/graphql-attachments-service.d.ts

@@ -0,0 +1,12 @@
+import type { LinearAttachment } from "../types/linear.js";
+import type { AuthOptions } from "./auth.js";
+import { type GraphQLService } from "./graphql-service.js";
+declare class GraphQLAttachmentsService {
+    private readonly graphqlService;
+    constructor(graphqlService: GraphQLService);
+    createAttachment(input: Record<string, unknown>): Promise<LinearAttachment>;
+    deleteAttachment(id: string): Promise<boolean>;
+    listAttachments(issueId: string): Promise<LinearAttachment[]>;
+}
+export declare function createGraphQLAttachmentsService(options: AuthOptions): GraphQLAttachmentsService;
+export {};

package/dist/utils/graphql-attachments-service.js

@@ -0,0 +1,46 @@
+import { CREATE_ATTACHMENT_MUTATION, DELETE_ATTACHMENT_MUTATION, LIST_ATTACHMENTS_QUERY, } from "../queries/attachments.js";
+import { createGraphQLService, } from "./graphql-service.js";
+function transformAttachment(att) {
+    return {
+        id: att.id,
+        url: att.url,
+        title: att.title || undefined,
+        createdAt: att.createdAt || undefined,
+        updatedAt: att.updatedAt || undefined,
+    };
+}
+class GraphQLAttachmentsService {
+    graphqlService;
+    constructor(graphqlService) {
+        this.graphqlService = graphqlService;
+    }
+    async createAttachment(input) {
+        const result = await this.graphqlService.rawRequest(CREATE_ATTACHMENT_MUTATION, { input });
+        const attachmentCreate = result.attachmentCreate;
+        if (!attachmentCreate.success) {
+            throw new Error(`Failed to create attachment on issue ${input.issueId} for URL "${input.url}"`);
+        }
+        return transformAttachment(attachmentCreate.attachment);
+    }
+    async deleteAttachment(id) {
+        const result = await this.graphqlService.rawRequest(DELETE_ATTACHMENT_MUTATION, { id });
+        const attachmentDelete = result.attachmentDelete;
+        if (!attachmentDelete.success) {
+            throw new Error(`Failed to delete attachment: ${id}`);
+        }
+        return true;
+    }
+    async listAttachments(issueId) {
+        const result = await this.graphqlService.rawRequest(LIST_ATTACHMENTS_QUERY, { issueId });
+        if (!result.issue) {
+            throw new Error(`Issue not found: ${issueId}`);
+        }
+        const issue = result.issue;
+        const attachments = issue.attachments;
+        return attachments.nodes.map(transformAttachment);
+    }
+}
+export function createGraphQLAttachmentsService(options) {
+    const graphqlService = createGraphQLService(options);
+    return new GraphQLAttachmentsService(graphqlService);
+}

package/dist/utils/graphql-documents-service.d.ts

@@ -0,0 +1,18 @@
+import type { LinearDocument } from "../types/linear.js";
+import type { AuthOptions } from "./auth.js";
+import { type GraphQLService } from "./graphql-service.js";
+declare class GraphQLDocumentsService {
+    private readonly graphqlService;
+    constructor(graphqlService: GraphQLService);
+    createDocument(input: Record<string, unknown>): Promise<LinearDocument>;
+    updateDocument(id: string, input: Record<string, unknown>): Promise<LinearDocument>;
+    getDocument(id: string): Promise<LinearDocument>;
+    listDocuments(options?: {
+        projectId?: string;
+        first?: number;
+    }): Promise<LinearDocument[]>;
+    deleteDocument(id: string): Promise<boolean>;
+    listDocumentsBySlugIds(slugIds: string[], limit?: number): Promise<LinearDocument[]>;
+}
+export declare function createGraphQLDocumentsService(options: AuthOptions): GraphQLDocumentsService;
+export {};