npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@frogbotai/piece-linear

v0.42.0

Published

Linear tools for FrogBot.

Readme

@frogbotai/piece-linear

Manage Linear issues, projects, comments, webhook events, and Agent Session conversations.

Usage

import { createLinear } from '@frogbotai/piece-linear';

export const linear = createLinear({ auth: { apiKey: process.env.LINEAR_API_KEY! } });

API keys and OAuth access tokens use FrogBot's current connection resolution. OAuth application credentials configure the connection flow; the resulting access token is the piece credential.

Enable the credential form with connections: [{ piece: linear, secret: true }]. Enter either apiKey or accessToken and omit the unused field. A user-linked credential takes precedence over factory auth for that user's action calls; channels continue using the fixed factory credential.

OAuth linking requires factory oauth: { clientId, clientSecret } and connections: [{ piece: linear, oauth: true }]. The built-in recipe requests actor=app: a workspace admin installs the application, and actions use the app's identity. It does not authorize actions as the installing user. For actions as a person, link their API key or an externally obtained user-actor OAuth access token through the credential form. FrogBot serializes the requested scopes with commas for Linear; see OAuth scopes to change them.

Channel setup

Agent Sessions are the primary channel mode. Create a Linear OAuth application under Settings > API > Applications, enable Agent Session webhook events, and have a workspace admin install it as an app actor with read, write, comments:create, issues:create, and app:mentionable scopes.

Set the OAuth application's webhook URL to this instance URL:

https://<host>/api/webhooks/<piece-instance-slug>

Select Agent session events and copy the application's webhook signing secret. Configure the installed OAuth access token and webhook secret:

export const linear = createLinear({
  auth: { accessToken: process.env.LINEAR_ACCESS_TOKEN! },
  webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
  botUsername: 'FrogBot',
});

Authorization-code OAuth access tokens expire after 24 hours. The channel adapter captures the static auth.accessToken and does not use FrogBot's user-connection refresh flow. Renew it through Linear's refresh-token endpoint, retain the replacement refresh token, update the configured access token, and restart the FrogBot runtime before expiry. Pasting an OAuth token into a secret connection also stores a static token; it does not enable automatic renewal.

For a personal API key bot that responds to issue comments, set channelMode: 'comments', subscribe an admin-created workspace webhook to Comments, and set botUsername to the name users mention. Comment mode supports post-and-edit streaming, but not Agent Session thoughts or native activity streaming.

Agents with the question tool ask in Agent Sessions with Linear's native elicitation: a single-choice question up to 25 options shows buttons, and other questions show numbered options answered by reply. Send stop request dismisses the question. Comment mode does not offer the tool. See Linear in the FrogBot docs.

Linear signs the exact request body in Linear-Signature with HMAC-SHA256. FrogBot rejects missing, invalid, or stale signed deliveries before channel or trigger dispatch. Channel replies are handled by the adapter; the triggers below remain independent per-subscription workflows.

OAuth scopes

Change the requested scopes with the factory's scopes option: createLinear({ oauth, scopes: ({ defaultScopes }) => [...defaultScopes, 'app:assignable'] }) adds one, and an array replaces the defaults. linearScopes maps each name to the provider's scope string.

  • Always requested: read.
  • Defaults: write, comments:create, issues:create, app:mentionable.
  • Also available: timeSchedule:write, admin, app:assignable.

Actions

| Upstream action slug | Previous wrapper export | Native action | Notes | | ----------------------- | ----------------------- | ----------------- | ---------------------------------------------------- | | linear_create_issue | linearCreateIssue | createIssue | | | linear_update_issue | linearUpdateIssue | updateIssue | | | linear_create_project | linearCreateProject | createProject | | | linear_update_project | linearUpdateProject | updateProject | Previously exposed but omitted from linearActions. | | linear_create_comment | linearCreateComment | createComment | | | rawGraphqlQuery | rawGraphqlQuery | rawGraphqlQuery | |

Triggers

Set the factory's optional webhookSecret to enable webhook triggers. Actions continue to work without it; trigger subscription creation requires it. Each trigger registers its supplied /api/webhooks/<piece-instance-slug>/<subscription-id> URL and does not send channel replies.

The lifecycle creates and reads webhooks through Linear's API, which requires a workspace admin's API key or a user-actor OAuth token with admin scope. Linear's actor=app tokens cannot request admin, so the built-in OAuth recipe and Agent Session channel token cannot provision these subscriptions. Use a separately named piece instance with an admin API key for triggers when the channel uses app-actor OAuth; supply that instance's own webhook secret and subscription URLs. See Linear's webhook permissions and app-actor restrictions.

export const linearWebhooks = createLinear({
  slug: 'linear-webhooks',
  auth: { apiKey: process.env.LINEAR_ADMIN_API_KEY! },
  webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
});

FrogBot passes this secret to Linear when creating each webhook. Incoming requests must have a valid Linear-Signature HMAC-SHA256 signature over the raw body and a current signed body webhookTimestamp. Missing or invalid signatures, secrets, or timestamps are rejected.

| Upstream trigger slug | Native trigger | Type | Notes | | --------------------- | ---------------- | --------- | ----------------------------------------------------- | | new_comment | commentCreated | webhook | Optional team and author filters. | | new_issue | issueCreated | webhook | Team-scoped. | | updated_issue | issueUpdated | webhook | Optional team scope. | | removed_issue | issueRemoved | webhook | Team-scoped. | | new_project | projectCreated | webhook | Workspace-wide. | | updated_project | projectUpdated | webhook | Status changes with optional team and status filters. | | removed_project | projectRemoved | webhook | Workspace-wide. |