linkedin-mcp-server-ts: Skill for Claude Code

TypeScript Best Practices & Style Guide

Segue as diretrizes normativas consolidadas em .agents/rules/typescript-style.md, combinando o Google TypeScript Style Guide, ts.dev e os padrões modernos do ecossistema Bun/Biome/Zod/MCP.

---

1. Modelagem de Tipos: interface vs. type

• Use interface para formatos de objetos estruturados, contratos de classes, configurações (AppConfig) e opções de APIs/serviços:

  export interface ScraperOptions {
  	timeoutMs: number;
  	headless: boolean;
  	userAgent?: string;
  }
  

• Use type para Uniões Discriminadas, Branded Types, Tipos Utilitários/Mapeados e inferências Zod:

  export type ConnectionState =
  	| { status: "connectable"; actionText: string }
  	| { status: "already_connected" }
  	| { status: "pending" }
  	| { status: "unavailable" };
  

---

2. Torne Estados Ilegais Irrepresentáveis (Make Illegal States Unrepresentable)

Use o sistema de tipos para prevenir estados inválidos em tempo de compilação.

Uniões discriminadas para estados mutuamente exclusivos:

// Bom: apenas combinações válidas são possíveis
type RequestState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

// Ruim: permite combinações inválidas como { loading: true, error: Error }
type RequestState<T> = {
  loading: boolean;
  data?: T;
  error?: Error;
};

Branded types para primitivos de domínio:

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

// O compilador impede passar OrderId onde UserId é esperado
function getUser(id: UserId): Promise<User> { /* ... */ }

Const assertions para uniões literais (Banido enum tradicional):

const ROLES = ["admin", "user", "guest"] as const;
type Role = typeof ROLES[number]; // "admin" | "user" | "guest"

function isValidRole(role: string): role is Role {
  return ROLES.includes(role as Role);
}