@dahrk/linear 0.1.1 → 0.2.0

package/src/issues.ts

@@ -91,3 +91,52 @@ export function linearTriageApi(token: string): TriageApi {
     },
   };
 }
+
+/** The result of a Capture create/update: the issue's internal id plus its human identifier and url. */
+export interface CaptureIssueResult {
+  issueId: string;
+  identifier: string;
+  url: string;
+}
+
+/** The Capture Linear seam (DHK-1187): create an issue in a team (or under a project), or update an
+ *  existing one. Unlike {@link TriageApi}, it returns the issue's internal `issueId` too (a Capture
+ *  receipt needs it) and can update. Backed by a CUSTOMER connection token, never the hub triage token. */
+export interface CaptureLinearApi {
+  createIssue(input: {
+    teamKey: string;
+    projectName?: string;
+    title: string;
+    description: string;
+  }): Promise<CaptureIssueResult>;
+  updateIssue(input: { issueId: string; title: string; description: string }): Promise<CaptureIssueResult>;
+}
+
+/** The live {@link CaptureLinearApi} backed by a tenant connection token (API key or OAuth token). */
+export function linearCaptureApi(token: string): CaptureLinearApi {
+  const client = new LinearClient(linearClientAuth(token));
+  return {
+    async createIssue(input) {
+      const team = (await client.teams({ filter: { key: { eq: input.teamKey } } })).nodes[0];
+      if (!team) throw new Error(`capture team not found: ${input.teamKey}`);
+      let projectId: string | undefined;
+      if (input.projectName) {
+        projectId = (await client.projects({ filter: { name: { eq: input.projectName } } })).nodes[0]?.id;
+      }
+      const payload = await client.createIssue({
+        teamId: team.id,
+        title: input.title,
+        description: input.description,
+        ...(projectId ? { projectId } : {}),
+      });
+      const issue = await payload.issue;
+      return { issueId: issue?.id ?? "", identifier: issue?.identifier ?? "", url: issue?.url ?? "" };
+    },
+
+    async updateIssue(input) {
+      const payload = await client.updateIssue(input.issueId, { title: input.title, description: input.description });
+      const issue = await payload.issue;
+      return { issueId: issue?.id ?? input.issueId, identifier: issue?.identifier ?? "", url: issue?.url ?? "" };
+    },
+  };
+}

package/src/labels.ts

@@ -115,7 +115,7 @@ export async function provisionRepoLabels(
 /**
  * Fetch the child names of the issue's **project** `repo` label group (project labels are a separate
  * Linear namespace from issue labels, `Project.labels`). Returns the names of project labels whose
- * parent group is `repo` - e.g. `["skakel-site"]` - so the hub can bind every issue in that project to
+ * parent group is `repo` - e.g. `["dahrk-web"]` - so the hub can bind every issue in that project to
  * a repo via the project-label routing tier. Empty when the issue has no project, no project labels, or
  * no `repo` group. A read against the connection token; data assembly, not control flow, so the result
  * feeds deterministic routing and is snapshotted into the run.

package/src/linear-client.ts

@@ -79,11 +79,10 @@ export interface StateLike {
   type: string;
 }
 
-/** The configured review-state name. `DAHRK_` is the name; the legacy `SKAKEL_` prefix is still
- *  honoured so a host provisioned before the rename keeps working (DHK-440). This package has no
- *  dependency on the hub, so it cannot reuse the hub's `envRenamed`. */
+/** The configured review-state name. This package has no dependency on the hub, so it cannot reuse the
+ *  hub's `envValue`. The pre-rename legacy twin was dropped: no current host sets it. */
 function reviewStateNameEnv(): string | undefined {
-  return process.env.DAHRK_REVIEW_STATE_NAME ?? process.env.SKAKEL_REVIEW_STATE_NAME;
+  return process.env.DAHRK_REVIEW_STATE_NAME;
 }
 
 /** Find the review-target state the way `moveIssueToReview` does, so `startIssue` can EXCLUDE it.

package/src/oauth.ts

@@ -11,13 +11,17 @@ import { LinearClient } from "@linear/sdk";
 
 const AUTHORIZE_URL = "https://linear.app/oauth/authorize";
 const TOKEN_URL = "https://api.linear.app/oauth/token";
+const REVOKE_URL = "https://api.linear.app/oauth/revoke";
 
 /** The agent scopes: read/write plus the two that make the app assignable + mentionable. */
 export const DEFAULT_AGENT_SCOPES = ["read", "write", "app:assignable", "app:mentionable"] as const;
 
 export interface LinearTokens {
   accessToken: string;
-  /** Absent on some refresh responses; callers keep the prior refresh token when so. */
+  /** Present on every authorization-code and refresh response, absent on a client-credentials mint
+   *  (which issues no refresh token at all). It is NOT optional on a refresh: Linear rotates refresh
+   *  tokens single-use and always returns the replacement, so a refresh response without one is a
+   *  protocol violation rather than "keep the one you have" - see {@link refreshTokens}. */
   refreshToken?: string;
   /** When the access token expires (computed from `expires_in`). */
   expiresAt: Date;
@@ -155,7 +159,20 @@ export async function probeToken(accessToken: string): Promise<LinearProbe> {
   return probe;
 }
 
-/** Rotate the access token using the stored refresh token (the hub calls this near expiry / on 401). */
+/**
+ * Rotate the access token using the stored refresh token (the hub calls this near expiry / on 401).
+ *
+ * Linear rotates refresh tokens **single-use**: the request consumes the one presented and the response
+ * carries "a new valid access token and a new refresh token" (oauth-2-0-authentication.md, "Refresh an
+ * access token"). So the replacement is mandatory, and a response without one means the old token has
+ * been consumed while we learned nothing - the caller MUST NOT carry on with the previous value, which
+ * is now dead. Throwing here is what makes that loud instead of silently arming a connection to fail
+ * on its next refresh, forever (DHK-1306).
+ *
+ * Linear gives a 30-minute grace period for exactly this case: the original request can be replayed to
+ * retrieve the new refresh token. Recovery is the caller's to attempt; this function's job is to refuse
+ * to report success when the rotation is unaccounted for.
+ */
 export function refreshTokens(
   params: { clientId: string; clientSecret: string; refreshToken: string },
   now: () => Date = () => new Date(),
@@ -168,7 +185,51 @@ export function refreshTokens(
       refresh_token: params.refreshToken,
     },
     now,
-  );
+  ).then((t) => {
+    if (!t.refreshToken) {
+      throw new Error(
+        "linear refresh returned no replacement refresh token: the presented token is now consumed. " +
+          "Replay the same request within 30 minutes to recover it.",
+      );
+    }
+    return t;
+  });
+}
+
+/**
+ * Revoke an access token at Linear, de-authorising the app for the workspace that token belongs to.
+ *
+ * This is the ONLY app-callable lever Linear gives us over an install: there is no uninstall mutation
+ * and nothing in the GraphQL schema that names or targets an install (`revokeOauthToken`,
+ * `userAuthorizedApplications`, `applicationWithAuthorization` are all absent). De-authorisation is
+ * per organisation - Linear signals it with an `OAuthApp revoked` webhook carrying `organizationId`.
+ *
+ * Why it matters beyond hygiene: while an install exists, Linear's authorize hop resolves against it
+ * and shows "Dahrk already installed - Continue" rather than a consent screen for the workspace the
+ * user is actually in. So a user who wanted to move the connection to another workspace got the old
+ * one back, every time, with no way out from inside the product. Forgetting a token locally is not
+ * enough; Linear has to be told.
+ *
+ * A `400` counts as revoked. The endpoint returns it for an already-revoked token, and the caller's
+ * question is "is this token dead", to which "Linear dropped it earlier" is a yes. A `401` does not:
+ * it means we could not authenticate the revocation at all, so the install may well still be live and
+ * the caller must say so rather than report a clean disconnect.
+ */
+export async function revokeToken(params: {
+  token: string;
+  tokenTypeHint?: "access_token" | "refresh_token";
+}): Promise<void> {
+  const body: Record<string, string> = { token: params.token };
+  // Documented as optional but helpful; must not be combined with the legacy access_token/refresh_token
+  // form fields, which we never send.
+  if (params.tokenTypeHint) body.token_type_hint = params.tokenTypeHint;
+  const res = await fetch(REVOKE_URL, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(body).toString(),
+  });
+  if (res.ok || res.status === 400) return;
+  throw new Error(`linear revoke endpoint failed: ${res.status}`);
 }
 
 /**