@meetopenbot/linear 0.0.1

package/dist/oauth.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Linear OAuth 2.0 (authorization code + PKCE).
+ *
+ * Two callback modes:
+ * - Loopback: temporary localhost server (local runtimes).
+ * - Webhook: redirect to `https://<host>/api/webhooks/linear` (cloud/remote).
+ */
+import type { Storage } from "@meetopenbot/plugin-sdk";
+export declare const LINEAR_AUTHORIZE_URL = "https://linear.app/oauth/authorize";
+export declare const LINEAR_TOKEN_URL = "https://api.linear.app/oauth/token";
+export declare const LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql";
+export declare const OAUTH_WEBHOOK_PROVIDER = "linear";
+export interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    /** Epoch ms when the access token expires, if Linear reported expiry. */
+    expiresAt?: number;
+    scope?: string;
+}
+export interface StartOAuthFlowArgs {
+    clientId: string;
+    clientSecret?: string;
+    port: number;
+    scopes: string;
+    /** Called once the code has been exchanged successfully. */
+    onSuccess: (tokens: OAuthTokens) => Promise<void>;
+    onError?: (error: Error) => void;
+    /** How long the callback server stays alive, in ms. */
+    timeoutMs?: number;
+}
+export interface OAuthFlowHandle {
+    authorizeUrl: string;
+    redirectUri: string;
+    /** Resolves with tokens on success, null on timeout/cancel. */
+    completion: Promise<OAuthTokens | null>;
+    cancel: () => void;
+}
+export interface StartWebhookOAuthFlowArgs {
+    storage: Storage;
+    clientId: string;
+    clientSecret?: string;
+    scopes: string;
+    webhookBaseUrl: string;
+    timeoutMs?: number;
+}
+export declare function oauthHtmlPage(title: string, body: string, ok: boolean): string;
+export declare function buildOAuthRedirectUri(webhookBaseUrl: string): string;
+export declare function buildAuthorizeUrl(args: {
+    clientId: string;
+    redirectUri: string;
+    scopes: string;
+    state: string;
+    codeChallenge: string;
+}): string;
+export declare function exchangeAuthorizationCode(args: {
+    code: string;
+    redirectUri: string;
+    clientId: string;
+    clientSecret?: string;
+    codeVerifier: string;
+}): Promise<OAuthTokens>;
+export declare function refreshAccessToken(args: {
+    refreshToken: string;
+    clientId: string;
+    clientSecret?: string;
+}): Promise<OAuthTokens>;
+export declare function startWebhookOAuthFlow(args: StartWebhookOAuthFlowArgs): Promise<OAuthFlowHandle>;
+export type WebhookOAuthCallbackResult = {
+    kind: "oauth";
+    status: number;
+    html: string;
+    tokens: OAuthTokens | null;
+    state?: string;
+} | {
+    kind: "ignore";
+};
+export declare function handleWebhookOAuthCallback(args: {
+    storage: Storage;
+    query: Record<string, unknown>;
+    onSuccess: (tokens: OAuthTokens) => Promise<void>;
+}): Promise<WebhookOAuthCallbackResult>;
+export declare function startOAuthFlow(args: StartOAuthFlowArgs): OAuthFlowHandle;
+export declare function fetchViewer(accessToken: string): Promise<{
+    viewer: {
+        id: string;
+        name: string;
+        displayName: string;
+        email: string;
+    };
+    organization: {
+        id: string;
+        name: string;
+        urlKey: string;
+    };
+}>;

package/dist/oauth.js

@@ -0,0 +1,372 @@
+/**
+ * Linear OAuth 2.0 (authorization code + PKCE).
+ *
+ * Two callback modes:
+ * - Loopback: temporary localhost server (local runtimes).
+ * - Webhook: redirect to `https://<host>/api/webhooks/linear` (cloud/remote).
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { clearPendingOAuthSession, loadPendingOAuthSession, savePendingOAuthSession, } from "./oauth-pending.js";
+export const LINEAR_AUTHORIZE_URL = "https://linear.app/oauth/authorize";
+export const LINEAR_TOKEN_URL = "https://api.linear.app/oauth/token";
+export const LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql";
+export const OAUTH_WEBHOOK_PROVIDER = "linear";
+const LOOPBACK_CALLBACK_PATH = "/oauth/callback";
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const PENDING_SESSION_MS = 10 * 60 * 1000;
+let activeServer = null;
+const webhookOAuthCompletions = new Map();
+function base64url(buffer) {
+    return buffer
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+export function oauthHtmlPage(title, body, ok) {
+    return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${title}</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; background: #101012; color: #ededef; }
+  .card { text-align: center; padding: 48px 56px; border-radius: 16px; background: #1b1b1f; border: 1px solid #2a2a30; max-width: 420px; }
+  .icon { font-size: 44px; margin-bottom: 16px; }
+  h1 { font-size: 20px; margin: 0 0 8px; }
+  p { color: #9b9ba3; margin: 0; line-height: 1.5; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <div class="icon">${ok ? "✅" : "⚠️"}</div>
+    <h1>${title}</h1>
+    <p>${body}</p>
+  </div>
+</body>
+</html>`;
+}
+export function buildOAuthRedirectUri(webhookBaseUrl) {
+    const base = webhookBaseUrl.replace(/\/$/, "");
+    return `${base}/api/webhooks/${OAUTH_WEBHOOK_PROVIDER}`;
+}
+function generatePkce() {
+    const state = base64url(randomBytes(24));
+    const codeVerifier = base64url(randomBytes(48));
+    const codeChallenge = base64url(createHash("sha256").update(codeVerifier).digest());
+    return { state, codeVerifier, codeChallenge };
+}
+export function buildAuthorizeUrl(args) {
+    return (`${LINEAR_AUTHORIZE_URL}?` +
+        new URLSearchParams({
+            client_id: args.clientId,
+            redirect_uri: args.redirectUri,
+            response_type: "code",
+            scope: args.scopes,
+            state: args.state,
+            prompt: "consent",
+            code_challenge: args.codeChallenge,
+            code_challenge_method: "S256",
+        }).toString());
+}
+export async function exchangeAuthorizationCode(args) {
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        code: args.code,
+        redirect_uri: args.redirectUri,
+        client_id: args.clientId,
+        code_verifier: args.codeVerifier,
+    });
+    if (args.clientSecret)
+        body.set("client_secret", args.clientSecret);
+    const response = await fetch(LINEAR_TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+    });
+    const payload = (await response.json().catch(() => ({})));
+    if (!response.ok || typeof payload.access_token !== "string") {
+        const detail = typeof payload.error_description === "string"
+            ? payload.error_description
+            : JSON.stringify(payload);
+        throw new Error(`Linear token exchange failed (${response.status}): ${detail}`);
+    }
+    return normalizeTokenResponse(payload);
+}
+export async function refreshAccessToken(args) {
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: args.refreshToken,
+        client_id: args.clientId,
+    });
+    if (args.clientSecret)
+        body.set("client_secret", args.clientSecret);
+    const response = await fetch(LINEAR_TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+    });
+    const payload = (await response.json().catch(() => ({})));
+    if (!response.ok || typeof payload.access_token !== "string") {
+        const detail = typeof payload.error_description === "string"
+            ? payload.error_description
+            : JSON.stringify(payload);
+        throw new Error(`Linear token refresh failed (${response.status}): ${detail}`);
+    }
+    return normalizeTokenResponse(payload);
+}
+function normalizeTokenResponse(payload) {
+    return {
+        accessToken: payload.access_token,
+        refreshToken: typeof payload.refresh_token === "string"
+            ? payload.refresh_token
+            : undefined,
+        expiresAt: typeof payload.expires_in === "number"
+            ? Date.now() + payload.expires_in * 1000
+            : undefined,
+        scope: Array.isArray(payload.scope)
+            ? payload.scope.join(",")
+            : payload.scope,
+    };
+}
+function registerWebhookOAuthCompletion(state, timeoutMs) {
+    return new Promise((resolve) => {
+        const existing = webhookOAuthCompletions.get(state);
+        if (existing) {
+            webhookOAuthCompletions.delete(state);
+        }
+        const timeout = setTimeout(() => {
+            webhookOAuthCompletions.delete(state);
+            resolve(null);
+        }, timeoutMs);
+        timeout.unref?.();
+        webhookOAuthCompletions.set(state, (tokens) => {
+            clearTimeout(timeout);
+            resolve(tokens);
+        });
+    });
+}
+function settleWebhookOAuthCompletion(state, tokens) {
+    const resolve = webhookOAuthCompletions.get(state);
+    if (!resolve)
+        return;
+    webhookOAuthCompletions.delete(state);
+    resolve(tokens);
+}
+export async function startWebhookOAuthFlow(args) {
+    const { state, codeVerifier, codeChallenge } = generatePkce();
+    const redirectUri = buildOAuthRedirectUri(args.webhookBaseUrl);
+    const pending = {
+        state,
+        codeVerifier,
+        clientId: args.clientId,
+        clientSecret: args.clientSecret,
+        redirectUri,
+        expiresAt: Date.now() + PENDING_SESSION_MS,
+    };
+    await savePendingOAuthSession(args.storage, pending);
+    const authorizeUrl = buildAuthorizeUrl({
+        clientId: args.clientId,
+        redirectUri,
+        scopes: args.scopes,
+        state,
+        codeChallenge,
+    });
+    const timeoutMs = args.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const completion = registerWebhookOAuthCompletion(state, timeoutMs);
+    return {
+        authorizeUrl,
+        redirectUri,
+        completion,
+        cancel: () => {
+            settleWebhookOAuthCompletion(state, null);
+            void clearPendingOAuthSession(args.storage);
+        },
+    };
+}
+export async function handleWebhookOAuthCallback(args) {
+    const code = queryParam(args.query, "code");
+    const state = queryParam(args.query, "state");
+    const oauthError = queryParam(args.query, "error");
+    if (!code && !state && !oauthError) {
+        return { kind: "ignore" };
+    }
+    if (oauthError) {
+        if (state)
+            settleWebhookOAuthCompletion(state, null);
+        await clearPendingOAuthSession(args.storage);
+        return {
+            kind: "oauth",
+            status: 400,
+            html: oauthHtmlPage("Connection failed", `Linear returned: ${oauthError}. Return to OpenBot and try again.`, false),
+            tokens: null,
+            state,
+        };
+    }
+    const pending = await loadPendingOAuthSession(args.storage);
+    if (!pending || !code || !state || pending.state !== state) {
+        return {
+            kind: "oauth",
+            status: 400,
+            html: oauthHtmlPage("Connection failed", "Invalid callback (missing code or state mismatch). Return to OpenBot and try again.", false),
+            tokens: null,
+            state,
+        };
+    }
+    try {
+        const tokens = await exchangeAuthorizationCode({
+            code,
+            redirectUri: pending.redirectUri,
+            clientId: pending.clientId,
+            clientSecret: pending.clientSecret,
+            codeVerifier: pending.codeVerifier,
+        });
+        await args.onSuccess(tokens);
+        await clearPendingOAuthSession(args.storage);
+        settleWebhookOAuthCompletion(state, tokens);
+        return {
+            kind: "oauth",
+            status: 200,
+            html: oauthHtmlPage("Connected to Linear", "You can close this tab and return to OpenBot.", true),
+            tokens,
+            state,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await clearPendingOAuthSession(args.storage);
+        settleWebhookOAuthCompletion(state, null);
+        return {
+            kind: "oauth",
+            status: 500,
+            html: oauthHtmlPage("Connection failed", `${message}. Return to OpenBot and try again.`, false),
+            tokens: null,
+            state,
+        };
+    }
+}
+function queryParam(query, key) {
+    const value = query[key];
+    if (typeof value === "string" && value.trim())
+        return value.trim();
+    if (Array.isArray(value) && typeof value[0] === "string") {
+        return value[0].trim();
+    }
+    return undefined;
+}
+export function startOAuthFlow(args) {
+    if (activeServer) {
+        activeServer.close();
+        activeServer = null;
+    }
+    const { state, codeVerifier, codeChallenge } = generatePkce();
+    const redirectUri = `http://localhost:${args.port}${LOOPBACK_CALLBACK_PATH}`;
+    const authorizeUrl = buildAuthorizeUrl({
+        clientId: args.clientId,
+        redirectUri,
+        scopes: args.scopes,
+        state,
+        codeChallenge,
+    });
+    let settle;
+    const completion = new Promise((resolve) => {
+        settle = resolve;
+    });
+    const server = createServer(async (req, res) => {
+        const url = new URL(req.url ?? "/", `http://localhost:${args.port}`);
+        if (url.pathname !== LOOPBACK_CALLBACK_PATH) {
+            res.writeHead(404).end();
+            return;
+        }
+        const finish = (status, title, body, ok) => {
+            res.writeHead(status, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(oauthHtmlPage(title, body, ok));
+        };
+        const error = url.searchParams.get("error");
+        if (error) {
+            finish(400, "Connection failed", `Linear returned: ${error}. Return to OpenBot and try again.`, false);
+            cleanup();
+            args.onError?.(new Error(`Linear authorization failed: ${error}`));
+            settle(null);
+            return;
+        }
+        const code = url.searchParams.get("code");
+        if (!code || url.searchParams.get("state") !== state) {
+            finish(400, "Connection failed", "Invalid callback (missing code or state mismatch). Return to OpenBot and try again.", false);
+            return;
+        }
+        try {
+            const tokens = await exchangeAuthorizationCode({
+                code,
+                redirectUri,
+                clientId: args.clientId,
+                clientSecret: args.clientSecret,
+                codeVerifier,
+            });
+            await args.onSuccess(tokens);
+            finish(200, "Connected to Linear", "You can close this tab and return to OpenBot.", true);
+            cleanup();
+            settle(tokens);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            finish(500, "Connection failed", `${message}. Return to OpenBot and try again.`, false);
+            cleanup();
+            args.onError?.(error instanceof Error ? error : new Error(message));
+            settle(null);
+        }
+    });
+    const timeout = setTimeout(() => {
+        cleanup();
+        settle(null);
+    }, args.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    timeout.unref?.();
+    function cleanup() {
+        clearTimeout(timeout);
+        if (activeServer === server)
+            activeServer = null;
+        server.close();
+    }
+    server.on("error", (error) => {
+        cleanup();
+        args.onError?.(error);
+        settle(null);
+    });
+    server.listen(args.port);
+    activeServer = server;
+    return {
+        authorizeUrl,
+        redirectUri,
+        completion,
+        cancel: () => {
+            cleanup();
+            settle(null);
+        },
+    };
+}
+export async function fetchViewer(accessToken) {
+    const response = await fetch(LINEAR_GRAPHQL_URL, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${accessToken}`,
+        },
+        body: JSON.stringify({
+            query: `query { viewer { id name displayName email } organization { id name urlKey } }`,
+        }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Linear API request failed (${response.status}): ${body.slice(0, 500)}`);
+    }
+    const payload = (await response.json());
+    if (payload.errors?.length) {
+        throw new Error(payload.errors.map((e) => e.message).join("; "));
+    }
+    if (!payload.data) {
+        throw new Error("Linear API returned no data.");
+    }
+    return payload.data;
+}

package/dist/tools.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Linear tool implementations. Each tool returns structured `data` for the
+ * model plus a human-readable `output` summary, and optionally a UI widget
+ * spec rendered in the OpenBot client.
+ */
+import type { RenderUIWidgetData, ToolDefinition } from '@meetopenbot/plugin-sdk';
+import { type LinearAuth } from './api.js';
+export interface ToolRunResult {
+    data: unknown;
+    output: string;
+    widget?: RenderUIWidgetData;
+}
+export interface LinearTool {
+    definition: ToolDefinition;
+    run: (auth: LinearAuth, args: Record<string, unknown>) => Promise<ToolRunResult>;
+}
+export declare const linearTools: Record<string, LinearTool>;