linear-sdk-cli 0.1.0

package/src/services/user.ts

@@ -0,0 +1,137 @@
+/**
+ * User service: all SDK access for users lives here so commands stay thin.
+ *
+ * The workspace user list goes through the typed `client.users()` connection;
+ * single `view`/`me` resolve a user id via `resolveUserId` (handling me / email /
+ * name / id) and read the typed SDK model. This group is read-only.
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { shape } from "../lib/shape.js";
+import { collect, inheritPaginationMetadata, pageSize } from "../lib/pagination.js";
+import { resolveUserId } from "../lib/resolve.js";
+
+export interface UserRow {
+  id: string;
+  displayName: string;
+  name: string;
+  email: string;
+  active: boolean;
+  admin: boolean;
+  guest: boolean;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const USER_ROW_SHAPE = shape<UserRow>({
+  id: "string",
+  displayName: "string",
+  name: "string",
+  email: "string",
+  active: "boolean",
+  admin: "boolean",
+  guest: "boolean",
+});
+
+/**
+ * List the workspace's users. Linear defaults `includeDisabled` to false, so
+ * deactivated users are invisible (and the `active` column constantly true)
+ * unless the caller opts in.
+ */
+export async function listUsers(
+  client: LinearClient,
+  limit: number,
+  includeDisabled = false,
+): Promise<UserRow[]> {
+  const conn = await withRetry(() => client.users({ first: pageSize(limit), includeDisabled }));
+  const nodes = await collect(conn as any, limit);
+  return inheritPaginationMetadata(nodes.map(toRow), nodes);
+}
+
+export interface UserDetail {
+  id: string;
+  displayName: string;
+  name: string;
+  email: string;
+  active: boolean;
+  admin: boolean;
+  guest: boolean;
+  isMe: boolean;
+  description: string | null;
+  statusLabel: string | null;
+  timezone: string | null;
+  url: string;
+  avatarUrl: string | null;
+  lastSeen: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** The detail's shape; checked against `UserDetail`. */
+export const USER_DETAIL_SHAPE = shape<UserDetail>({
+  id: "string",
+  displayName: "string",
+  name: "string",
+  email: "string",
+  active: "boolean",
+  admin: "boolean",
+  guest: "boolean",
+  isMe: "boolean",
+  description: "string|null",
+  statusLabel: "string|null",
+  timezone: "string|null",
+  url: "string",
+  avatarUrl: "string|null",
+  lastSeen: "string|null",
+  createdAt: "string",
+  updatedAt: "string",
+});
+
+/**
+ * Resolve a user reference (`me`, email, name, or id) and return its detail.
+ * `resolveUserId` handles the `me`/email/name/id ergonomics.
+ */
+export async function getUserDetail(client: LinearClient, idArg: string): Promise<UserDetail> {
+  const userId = await resolveUserId(client, idArg);
+  const user = await withRetry(() => client.user(userId));
+  return toDetail(user);
+}
+
+/** The authenticated viewer. */
+export async function getViewer(client: LinearClient): Promise<UserDetail> {
+  const user = await withRetry(() => client.viewer);
+  return toDetail(user);
+}
+
+function toRow(u: any): UserRow {
+  return {
+    id: u.id,
+    displayName: u.displayName,
+    name: u.name,
+    email: u.email,
+    active: !!u.active,
+    admin: !!u.admin,
+    guest: !!u.guest,
+  };
+}
+
+function toDetail(u: any): UserDetail {
+  return {
+    id: u.id,
+    displayName: u.displayName,
+    name: u.name,
+    email: u.email,
+    active: !!u.active,
+    admin: !!u.admin,
+    guest: !!u.guest,
+    isMe: !!u.isMe,
+    description: u.description ?? null,
+    statusLabel: u.statusLabel ?? null,
+    timezone: u.timezone ?? null,
+    url: u.url,
+    avatarUrl: u.avatarUrl ?? null,
+    lastSeen: u.lastSeen?.toISOString?.() ?? (u.lastSeen ? String(u.lastSeen) : null),
+    createdAt: u.createdAt?.toISOString?.() ?? String(u.createdAt),
+    updatedAt: u.updatedAt?.toISOString?.() ?? String(u.updatedAt),
+  };
+}

package/src/services/webhook.ts

@@ -0,0 +1,203 @@
+/**
+ * Webhook service: all SDK access for webhooks lives here so commands stay thin.
+ *
+ * Webhooks are workspace-scoped (optionally team-scoped). The list uses the typed
+ * SDK connection (relation-light: no per-row fetches), `view` reads a single model,
+ * and mutations unwrap the `{ success, webhook }` payload.
+ */
+
+import { type LinearClient, WebhookResourceType } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { shape } from "../lib/shape.js";
+import { collect, inheritPaginationMetadata, pageSize } from "../lib/pagination.js";
+import { usageError, notFound, normalizeError } from "../lib/errors.js";
+import { assertMutation, unwrapMutation } from "../lib/mutation.js";
+import { resolveTeam } from "../lib/resolve.js";
+
+/** The valid webhook resource-type strings (e.g. "Issue", "IssueSLA"). */
+const RESOURCE_TYPES = Object.values(WebhookResourceType);
+const RESOURCE_BY_LOWER = new Map(RESOURCE_TYPES.map((t) => [t.toLowerCase(), t]));
+
+/**
+ * Validate and normalize user-supplied resource types against the SDK enum,
+ * case-insensitively, so a typo or `issue` becomes a clean usage error (with the
+ * valid list) instead of an opaque API validation failure.
+ */
+export function normalizeResourceTypes(input: string[]): string[] {
+  const out: string[] = [];
+  for (const raw of input) {
+    const match = RESOURCE_BY_LOWER.get(raw.toLowerCase());
+    if (!match) {
+      throw usageError(
+        `Unknown webhook resource type '${raw}'. Valid types: ${RESOURCE_TYPES.join(", ")}`,
+      );
+    }
+    if (!out.includes(match)) out.push(match);
+  }
+  return out;
+}
+
+export interface WebhookRow {
+  id: string;
+  url: string | null;
+  enabled: boolean;
+  resourceTypes: string[];
+  label: string | null;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const WEBHOOK_ROW_SHAPE = shape<WebhookRow>({
+  id: "string",
+  url: "string|null",
+  enabled: "boolean",
+  resourceTypes: ["string"],
+  label: "string|null",
+});
+
+/** All webhooks in the workspace (relation-light, so no N+1). */
+export async function listWebhooks(client: LinearClient, limit: number): Promise<WebhookRow[]> {
+  const conn = await withRetry(() => client.webhooks({ first: pageSize(limit) }));
+  const nodes = await collect(conn as any, limit);
+  return inheritPaginationMetadata(
+    nodes.map((w: any) => ({
+      id: w.id,
+      url: w.url ?? null,
+      enabled: w.enabled,
+      resourceTypes: w.resourceTypes ?? [],
+      label: w.label ?? null,
+    })),
+    nodes,
+  );
+}
+
+export interface WebhookDetail {
+  id: string;
+  url: string | null;
+  enabled: boolean;
+  resourceTypes: string[];
+  label: string | null;
+  allPublicTeams: boolean;
+  team: string | null;
+  creator: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** The detail's shape; checked against `WebhookDetail`. */
+export const WEBHOOK_DETAIL_SHAPE = shape<WebhookDetail>({
+  id: "string",
+  url: "string|null",
+  enabled: "boolean",
+  resourceTypes: ["string"],
+  label: "string|null",
+  allPublicTeams: "boolean",
+  team: "string|null",
+  creator: "string|null",
+  createdAt: "string",
+  updatedAt: "string",
+});
+
+export async function getWebhookDetail(client: LinearClient, id: string): Promise<WebhookDetail> {
+  const webhook = await withRetry(() => client.webhook(id));
+  const [team, creator] = await Promise.all([webhook.team, webhook.creator]);
+  return {
+    id: webhook.id,
+    url: webhook.url ?? null,
+    enabled: webhook.enabled,
+    resourceTypes: webhook.resourceTypes ?? [],
+    label: webhook.label ?? null,
+    allPublicTeams: webhook.allPublicTeams,
+    team: team ? `${team.key} ${team.name}` : null,
+    creator: creator?.displayName ?? null,
+    createdAt: webhook.createdAt.toISOString(),
+    updatedAt: webhook.updatedAt.toISOString(),
+  };
+}
+
+export interface CreateOptions {
+  url: string;
+  resourceTypes: string[];
+  /** Team to scope the webhook to (key/name/id); from the global --team. */
+  team?: string;
+  label?: string;
+  allPublicTeams?: boolean;
+  secret?: string;
+}
+
+/** Build a WebhookCreateInput, resolving the team reference (if any) to an id. */
+export async function createWebhook(client: LinearClient, opts: CreateOptions) {
+  if (!opts.url) throw usageError("A webhook needs a --url.");
+  if (!opts.resourceTypes?.length)
+    throw usageError("A webhook needs at least one --resource (e.g. Issue, Comment, Project).");
+
+  // A webhook must be scoped to a team or explicitly to all public teams.
+  if (!opts.team && !opts.allPublicTeams) {
+    throw usageError(
+      "A webhook needs a scope: pass --team <KEY> (or set a default team) or --all-public.",
+    );
+  }
+
+  const input: Record<string, any> = {
+    url: opts.url,
+    resourceTypes: normalizeResourceTypes(opts.resourceTypes),
+  };
+  // --all-public and a specific team are mutually exclusive; prefer all-public.
+  if (opts.allPublicTeams) input.allPublicTeams = true;
+  else if (opts.team) input.teamId = (await resolveTeam(client, opts.team, undefined)).id;
+  if (opts.label !== undefined) input.label = opts.label;
+  if (opts.secret !== undefined) input.secret = opts.secret;
+
+  return unwrapMutation(
+    withRetry(() => client.createWebhook(input as any)),
+    "webhook",
+    "Webhook creation",
+  );
+}
+
+export interface UpdateOptions {
+  url?: string;
+  enabled?: boolean;
+  resourceTypes?: string[];
+  label?: string;
+  secret?: string;
+}
+
+export async function updateWebhook(client: LinearClient, id: string, opts: UpdateOptions) {
+  const input: Record<string, any> = {};
+  if (opts.url !== undefined) input.url = opts.url;
+  if (opts.enabled !== undefined) input.enabled = opts.enabled;
+  if (opts.resourceTypes !== undefined) {
+    if (!opts.resourceTypes.length)
+      throw usageError("--resource needs at least one resource type.");
+    input.resourceTypes = normalizeResourceTypes(opts.resourceTypes);
+  }
+  if (opts.label !== undefined) input.label = opts.label;
+  if (opts.secret !== undefined) input.secret = opts.secret;
+
+  if (Object.keys(input).length === 0)
+    throw usageError(
+      "Nothing to update; pass at least one of --url, --enabled/--disabled, --resource.",
+    );
+
+  return unwrapMutation(
+    withRetry(() => client.updateWebhook(id, input as any)),
+    "webhook",
+    "Webhook update",
+  );
+}
+
+export async function deleteWebhook(client: LinearClient, id: string): Promise<WebhookDetail> {
+  let webhook: WebhookDetail;
+  try {
+    webhook = await getWebhookDetail(client, id);
+  } catch (err) {
+    const normalized = normalizeError(err);
+    if (normalized.code === "not_found") throw notFound(`No webhook matching '${id}'.`);
+    throw normalized;
+  }
+  await assertMutation(
+    withRetry(() => client.deleteWebhook(id)),
+    "Webhook deletion",
+  );
+  return webhook;
+}