convex-linear 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,438 @@
+# convex-linear
+
+Sync Linear issues and comments into your Convex database reactively, and create, update, comment on, and archive issues directly from Convex functions.
+
+[![npm version](https://img.shields.io/npm/v/convex-linear)](https://www.npmjs.com/package/convex-linear)
+[![Convex Component](https://www.convex.dev/components/badge/sholajegede/convex-linear)](https://www.convex.dev/components/sholajegede/convex-linear)
+[![npm downloads](https://img.shields.io/npm/dw/convex-linear)](https://www.npmjs.com/package/convex-linear)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
+
+```ts
+const linear = new Linear(components.convexLinear, {
+  apiKey: process.env.LINEAR_API_KEY!,
+  webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+});
+
+// File an issue and get it back immediately — no waiting on the webhook
+const { identifier, url } = await linear.createIssue(ctx, {
+  teamId: "team_...",
+  title: "Ship the launch checklist",
+});
+
+// Every issue for that team stays live from here on, updated the
+// instant something changes in Linear — including edits made outside
+// your app, like someone archiving it from Linear's own UI
+const issues = useQuery(api.example.listIssuesByTeam, { teamId: "team_..." });
+```
+
+<!-- START: Include on https://convex.dev/components -->
+
+## What this does
+
+`convex-linear` gives your Convex app a live, queryable mirror of Linear issues and comments for the teams you care about, kept up to date by Linear webhooks, plus a small set of actions for driving Linear from your own backend logic:
+
+- **Reactive issue & comment tracking** — every `Issue` and `Comment` webhook event updates a Convex table, so `useQuery` in your React app re-renders the instant something changes in Linear.
+- **Create, update, comment, archive** — call `createIssue`, `updateIssue`, `createComment`, `archiveIssue`, and `unarchiveIssue` from Convex actions using the Linear GraphQL API.
+- **Idempotent by delivery ID** — every webhook delivery is recorded by its `Linear-Delivery` ID, so retried deliveries never double-process.
+- **Signature and freshness verified** — every inbound webhook is verified against `Linear-Signature` with a constant-time HMAC-SHA256 comparison, and rejected if `Linear-Timestamp` is more than 60 seconds old, before anything is written.
+
+This is a [Convex component](https://convex.dev/components): its `issues`, `comments`, and `webhookEvents` tables live in an isolated schema, not your app's schema, and are only reachable through the functions this component exposes.
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Setup](#setup)
+- [Usage](#usage)
+- [API Reference](#api-reference)
+- [Type Reference](#type-reference)
+- [Webhook Events](#webhook-events)
+- [Database Schema](#database-schema)
+- [Authentication](#authentication)
+- [Example App](#example-app)
+- [Testing](#testing)
+- [Limitations](#limitations)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+
+## Install
+
+```sh
+npm install convex-linear
+```
+
+## Quick Start
+
+### 1. Add the component
+
+```ts
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import convexLinear from "convex-linear/convex.config";
+
+const app = defineApp();
+app.use(convexLinear);
+
+export default app;
+```
+
+### 2. Set environment variables
+
+```sh
+npx convex env set LINEAR_API_KEY lin_api_...
+npx convex env set LINEAR_WEBHOOK_SECRET whsec_...
+```
+
+`LINEAR_API_KEY` is a personal API key (Settings → API → Personal API keys) or an OAuth access token. `LINEAR_WEBHOOK_SECRET` is the signing secret shown when you create the webhook in step 4.
+
+### 3. Mount the webhook handler
+
+```ts
+// convex/http.ts
+import { httpRouter } from "convex/server";
+import { components } from "./_generated/api";
+import { Linear } from "convex-linear";
+
+const linear = new Linear(components.convexLinear, {
+  apiKey: process.env.LINEAR_API_KEY!,
+  webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+});
+
+const http = httpRouter();
+
+http.route({
+  path: "/webhooks/linear",
+  method: "POST",
+  handler: linear.webhookHandler,
+});
+
+export default http;
+```
+
+### 4. Register the webhook in Linear
+
+In your workspace's **Settings → API → Webhooks**, add a webhook pointing at `https://<your-deployment>.convex.site/webhooks/linear`, and subscribe to the **Issues** and **Comments** resource types. Copy the signing secret Linear shows you into `LINEAR_WEBHOOK_SECRET`.
+
+### 5. Initialize the client
+
+```ts
+// convex/example.ts
+import { action, query } from "./_generated/server";
+import { components } from "./_generated/api";
+import { Linear } from "convex-linear";
+import { v } from "convex/values";
+
+const linear = new Linear(components.convexLinear, {
+  apiKey: process.env.LINEAR_API_KEY!,
+  webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+});
+
+export const listIssuesByTeam = query({
+  args: { teamId: v.string() },
+  handler: async (ctx, args) => {
+    return await linear.listIssuesByTeam(ctx, args);
+  },
+});
+```
+
+## Setup
+
+The component needs no schema changes in your app — its tables (`issues`, `comments`, `webhookEvents`) live entirely inside the component's own isolated schema. All you need is the webhook mounted (step 3 above) and a `Linear` client instance wherever you call its methods.
+
+Issues and comments are keyed by Linear's own UUID `id` field, not by the human-readable identifier (e.g. `"ENG-123"`) — identifiers are stored too and are what you'd show in a UI, but lookups and upserts go through the UUID since that's what's stable across a team's issue-numbering changes.
+
+## Usage
+
+### Create an issue
+
+```ts
+export const fileIssue = action({
+  args: {
+    teamId: v.string(),
+    title: v.string(),
+    description: v.optional(v.string()),
+    priority: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    return await linear.createIssue(ctx, args);
+  },
+});
+```
+
+Returns `{ identifier, url }` and immediately records the full issue in Convex — you don't have to wait for the webhook round-trip to see it in a query.
+
+### Update an issue
+
+```ts
+export const reprioritize = action({
+  args: { issueId: v.string(), priority: v.number() },
+  handler: async (ctx, args) => {
+    await linear.updateIssue(ctx, args);
+    return null;
+  },
+});
+```
+
+Pass a `stateId` (a workflow state's UUID, found via Linear's GraphQL API or the URL when viewing a team's workflow settings) to move an issue between states — Linear's states are custom per team, so there's no fixed `"open"`/`"closed"` enum the way there is for GitHub issues.
+
+### Comment on an issue
+
+```ts
+export const comment = action({
+  args: { issueId: v.string(), body: v.string() },
+  handler: async (ctx, args) => {
+    return await linear.createComment(ctx, args);
+  },
+});
+```
+
+### Archive an issue
+
+```ts
+export const dismiss = action({
+  args: { issueId: v.string() },
+  handler: async (ctx, args) => {
+    await linear.archiveIssue(ctx, args);
+    return null;
+  },
+});
+```
+
+Archiving in Linear is a separate concept from closing — an archived issue is hidden from active views but is not deleted; it stays restorable from Linear's own archives page. This component mirrors that: `archiveIssue` sets the issue's `archivedAt` field in Convex rather than deleting its row, so an archived issue keeps showing up in `getIssue`/`listIssuesByTeam` with `archivedAt` set, and you decide whether to filter it out of your UI.
+
+**A note on how this is actually detected**, because it is not what you'd guess from Linear's docs alone: we tested this live against Linear's real API, and found that the `action` field on an `Issue` webhook delivery does *not* reliably indicate archived vs. trashed vs. deleted, and none of these deliveries carry `archivedAt` or `trashed` on their own payload:
+
+| What happened | Webhook `action` you actually get |
+| --- | --- |
+| `issueArchive` (soft archive, restorable) | `remove` |
+| `issueUnarchive` (restore from archive) | `restore` |
+| Moved to Linear's 30-day trash (e.g. "Delete issue" in the UI) | `update` |
+| Permanently gone (after 30 days in trash, or otherwise purged) | issue no longer exists at all |
+
+Because of this, the webhook handler does not branch on `action` for `Issue` events at all — every delivery re-fetches the issue's current state directly from Linear's GraphQL API and mirrors that (`archivedAt` and `trashed` included). The `action` is still recorded on the `webhookEvents` row for your own auditing, but the *only* thing that triggers an actual `removeIssue` (a hard delete of the local row) is the re-fetch itself failing with "Entity not found" — meaning the issue is genuinely, permanently gone. This does mean one extra Linear API call per `Issue` webhook delivery; see [Limitations](#limitations).
+
+### Unarchive an issue
+
+```ts
+export const restore = action({
+  args: { issueId: v.string() },
+  handler: async (ctx, args) => {
+    await linear.unarchiveIssue(ctx, args);
+    return null;
+  },
+});
+```
+
+Restores the issue in Linear and clears `archivedAt` on its Convex row.
+
+### Read issues and comments reactively
+
+```tsx
+const issues = useQuery(api.example.listIssuesByTeam, { teamId: "team_..." });
+```
+
+Every `Issue` and `Comment` webhook event patches, inserts, or removes a row, so this query re-renders live as issues move through your team's workflow — no polling.
+
+## API Reference
+
+### Actions (need `ctx` from an action)
+
+| Method | Description |
+| --- | --- |
+| `createIssue(ctx, { teamId, title, description?, priority?, assigneeId?, labelIds? })` | Creates a new issue via the GraphQL API and records it. Returns `{ identifier, url }`. |
+| `updateIssue(ctx, { issueId, title?, description?, stateId?, priority?, assigneeId?, labelIds? })` | Updates an issue's fields and re-records the full result. |
+| `createComment(ctx, { issueId, body })` | Posts a comment on an issue. Returns `{ id }`. |
+| `archiveIssue(ctx, { issueId })` | Archives an issue in Linear and sets `archivedAt` on its Convex row (the row is kept, not deleted). |
+| `unarchiveIssue(ctx, { issueId })` | Restores an archived issue in Linear and clears `archivedAt` on its Convex row. |
+
+### Queries (work from actions, queries, or mutations)
+
+| Method | Description |
+| --- | --- |
+| `getIssue(ctx, { issueId })` | Fetch one issue by its Linear UUID. |
+| `listIssuesByTeam(ctx, { teamId, limit? })` | Most recently updated issues for a team, newest first. |
+| `listCommentsByIssue(ctx, { issueId, limit? })` | Most recently updated comments for an issue, newest first. |
+
+### Webhook
+
+| Property | Description |
+| --- | --- |
+| `webhookHandler` | An `httpAction` that verifies, deduplicates, and processes `Issue` and `Comment` webhook deliveries. Mount it at any route. |
+
+## Type Reference
+
+```ts
+type LinearOptions = {
+  apiKey: string;        // personal API key or OAuth access token
+  webhookSecret: string; // the signing secret configured on the Linear webhook
+};
+
+type CreateIssueArgs = {
+  teamId: string;
+  title: string;
+  description?: string;
+  priority?: number;   // Linear's own scale: 0 none, 1 urgent, 2 high, 3 normal, 4 low
+  assigneeId?: string;
+  labelIds?: string[];
+};
+
+type UpdateIssueArgs = {
+  issueId: string;
+  title?: string;
+  description?: string;
+  stateId?: string;     // a workflow state's UUID
+  priority?: number;
+  assigneeId?: string;
+  labelIds?: string[];
+};
+
+type Issue = {
+  issueId: string;       // Linear's UUID
+  identifier: string;    // e.g. "ENG-123"
+  teamId: string;
+  title: string;
+  description?: string;
+  state: string;         // team-defined workflow state name
+  priority?: number;
+  assigneeId?: string;
+  assigneeName?: string;
+  labels?: string[];
+  url: string;
+  archivedAt?: number;   // set when Linear has archived the issue; absent/undefined otherwise
+  trashed?: boolean;     // set when the issue is in Linear's 30-day trash — distinct from archivedAt
+  createdAt: number;
+  updatedAt: number;
+};
+
+type Comment = {
+  commentId: string;     // Linear's UUID
+  issueId: string;
+  body: string;
+  userId?: string;
+  userName?: string;
+  createdAt: number;
+  updatedAt: number;
+};
+```
+
+## Webhook Events
+
+The webhook handler subscribes to two Linear resource types (set these when creating the webhook):
+
+- **`Issue`** — every delivery, regardless of its `action`, re-fetches the issue from Linear's API and upserts the result (including `archivedAt` and `trashed`); the row is only deleted if that re-fetch comes back "Entity not found" (the issue is genuinely, permanently gone). See [Archive an issue](#archive-an-issue) for why `action` alone can't be trusted here.
+- **`Comment`** — `create`/`update` actions upsert the comment into the `comments` table; `remove` is ignored (there is no dependent state to clean up, so a removed comment is left as a stale row rather than chasing down a delete).
+
+Every delivery is checked against `Linear-Signature` (HMAC-SHA256 of the raw request body, hex-encoded) with a constant-time comparison, checked for a `Linear-Timestamp` within 60 seconds of the current time (Linear's own recommendation against replay attacks), and deduplicated by `Linear-Delivery` before any table write.
+
+Other resource types (`Project`, `Cycle`, `IssueLabel`, etc.) are accepted by the route but ignored after signature verification and idempotency recording, so you can subscribe to more events later without needing a new endpoint.
+
+## Database Schema
+
+```ts
+issues: {
+  issueId: string;       // indexed: by_issueId — Linear's UUID
+  identifier: string;    // e.g. "ENG-123"
+  teamId: string;        // indexed: by_teamId
+  title: string;
+  description?: string;
+  state: string;
+  priority?: number;
+  assigneeId?: string;
+  assigneeName?: string;
+  labels?: string[];
+  url: string;
+  archivedAt?: number;   // set when Linear has archived the issue (not deleted)
+  trashed?: boolean;     // set when the issue is in Linear's 30-day trash
+  createdAt: number;
+  updatedAt: number;
+}
+
+comments: {
+  commentId: string;     // indexed: by_commentId — Linear's UUID
+  issueId: string;       // indexed: by_issueId
+  body: string;
+  userId?: string;
+  userName?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+
+webhookEvents: {
+  eventId: string;   // indexed: by_eventId — Linear-Delivery
+  eventType: string; // Linear-Event: "Issue" | "Comment" | ...
+  action?: string;   // payload.action: "create" | "update" | "remove" | "restore" — recorded for
+                      // auditing only; see Webhook Events for why Issue events don't branch on it
+  payload: string;   // raw JSON body, for auditing/replay
+  receivedAt: number;
+}
+```
+
+This schema lives entirely inside the component's isolated namespace — it will never collide with tables in your app's own `convex/schema.ts`.
+
+## Authentication
+
+Linear's GraphQL API accepts two kinds of tokens in the `Authorization` header, and they are **not** sent the same way:
+
+- A **personal API key** (the kind most integrations use, created under Settings → API) is sent as-is: `Authorization: lin_api_xxxxx` — no `Bearer ` prefix.
+- An **OAuth access token** (from a full OAuth app) does use the standard `Authorization: Bearer <token>` form.
+
+This component assumes a personal API key or an already-`Bearer`-formatted token is passed as `apiKey` — if you're using OAuth, prefix the token yourself (`Bearer ${accessToken}`) before passing it in, since the component sends whatever string you give it verbatim.
+
+## Example App
+
+The `example/` app is a full interactive demo, not just a form:
+
+- **Overview** — the landing tab: the pitch, a live tracker for issue/archived/comment/webhook counts (visible from every tab, not just this one), a team picker and "paste a team UUID" fallback, a walkthrough of how the archive/trash reconciliation actually works, and a quick-start code sample.
+- **Issues** — file an issue (with suggestion chips), reprioritize it, archive or restore it, and add comments, all reactively reflected the instant the action call returns — no waiting on the webhook.
+- **Webhooks** — a live, expandable feed of every raw delivery to `/webhooks/linear`, across every team you've connected, so you can watch signature verification, deduplication, and the ground-truth re-fetch happen in real time.
+- **History** — every issue and comment this component has ever recorded, newest first, across every team, with a one-click "file follow-up issue" action.
+- A sidebar **Activity** console logging every action call this demo makes, with its result or error.
+
+Run it from the repo root (not `example/`):
+
+```sh
+npm install --legacy-peer-deps
+npx convex env set LINEAR_API_KEY lin_api_...
+npx convex env set LINEAR_WEBHOOK_SECRET whsec_...
+npm run dev
+```
+
+Then register a webhook on a scratch team pointed at `https://<your-dev-deployment>.convex.site/webhooks/linear` (see [Quick Start](#quick-start)) to see live deliveries land in the Webhooks tab.
+
+## Testing
+
+```sh
+npm run test
+npm run typecheck
+```
+
+Tests use [`convex-test`](https://www.npmjs.com/package/convex-test) and cover `recordIssue` upsert behavior (including the `trashed` flag being carried through re-records), `listIssuesByTeam` scoping by team, `removeIssue` deletion, `setIssueArchived` archiving/restoring without deleting the row, `recordComment` upsert behavior, and webhook idempotency via `checkAndRecordEvent`.
+
+## Limitations
+
+- Only `Issue` and `Comment` webhook resource types are processed; `Project`, `Cycle`, `IssueLabel`, and other resource types are out of scope for this component.
+- All mutations (`createIssue`, `updateIssue`, `createComment`, `archiveIssue`, `unarchiveIssue`) go through Linear's GraphQL API directly — this component does not wrap every GraphQL mutation Linear exposes (e.g. issue relations, sub-issues, project updates).
+- The component does not manage webhook registration for you — you create the webhook once in Linear's UI or via the GraphQL API yourself.
+- Rate limits are Linear's own (complexity-based, roughly 1,500 points/hour for API keys) — this component does not implement its own rate limiting or backoff.
+- Every `Issue` webhook delivery makes one extra outbound call to Linear's GraphQL API (the re-fetch described in [Webhook Events](#webhook-events)) before writing anything to Convex — a deliberate tradeoff for correctness given `action` alone is unreliable, but worth knowing if you're watching Linear API usage closely. If that re-fetch throws for a reason other than "not found" (a transient network error, a rate limit), the webhook request fails; because the delivery was already marked processed for idempotency purposes before the re-fetch ran, a Linear-side retry of that same delivery will be treated as a duplicate and skipped rather than retried — in practice this means a very unlucky transient failure can leave one issue's mirror stale until its next change.
+
+## Troubleshooting
+
+**Webhook returns 401** — the signature didn't match. Double check `LINEAR_WEBHOOK_SECRET` matches exactly what Linear showed you when the webhook was created (this secret is only shown once).
+
+**Webhook returns 400 "Stale webhook timestamp"** — your Convex deployment's clock and Linear's disagree by more than 60 seconds, or the request took unusually long to arrive. This is intentionally strict to guard against replay; if you're testing with a manually-crafted request, make sure `Linear-Timestamp` is the current Unix time in milliseconds.
+
+**Issues never appear in queries** — confirm the webhook's delivery log in Linear shows a `200` response, and that the webhook is subscribed to the **Issues** and **Comments** resource types specifically.
+
+**`updateIssue` doesn't seem to change the state** — `stateId` must be the UUID of a workflow state that belongs to the issue's own team; state UUIDs are not shared across teams even when the state names look the same (e.g. every team has its own "In Progress").
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+<!-- END: Include on https://convex.dev/components -->

package/dist/client/_generated/_ignore.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=_ignore.d.ts.map

package/dist/client/_generated/_ignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_ignore.d.ts","sourceRoot":"","sources":["../../../src/client/_generated/_ignore.ts"],"names":[],"mappings":""}

package/dist/client/_generated/_ignore.js

@@ -0,0 +1,3 @@
+"use strict";
+// This is only here so convex-test can detect a _generated folder
+//# sourceMappingURL=_ignore.js.map

package/dist/client/_generated/_ignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_ignore.js","sourceRoot":"","sources":["../../../src/client/_generated/_ignore.ts"],"names":[],"mappings":";AAAA,kEAAkE"}