Pular para o conteúdo principal

API v1

Os recursos v1 ficam direto no cliente: client.projects, client.workItems, client.cycles e assim por diante. Toda chamada no escopo de um workspace recebe o slug do workspace primeiro e, depois, o id do projeto quando a URL tem um. Diferente da v2, aqui project é o UUID do projeto, e as classes mais antigas chamam o método de remoção de delete ou del (siga a lista de métodos que o seu editor mostra).

import { PlaneClient } from "@hoyasumii/plane";

const client = new PlaneClient({ apiKey: "your-api-key" });

const projects = await client.projects.list("workspace-slug");

const project = await client.projects.create("workspace-slug", {
  name: "My Project",
  description: "A new project",
});

const item = await client.workItems.create("workspace-slug", project.id, { name: "First task" });
await client.workItems.comments.create("workspace-slug", project.id, item.id, { comment_html: "<p>Hello</p>" });

// Um work item pela chave humana, no workspace inteiro.
const byKey = await client.workItems.retrieveByIdentifier("workspace-slug", "ENG-12");

Recursos​

  • Projects: gestão e organização de projetos
  • WorkItems: gestão de tarefas, com CRUD completo
  • WorkItemTypes: definição e gestão de tipos de work item customizados
  • WorkItemProperties: propriedades customizadas de work items
  • Labels: categorização por labels
  • States: estados do fluxo de trabalho
  • Users: usuários e perfis
  • Roles: papéis de workspace e de projeto (só leitura)
  • Estimates: estimativas de projeto e seus pontos
  • Modules: organização por módulos
  • Cycles: sprints e iterações
  • Customers: gestão de clientes
  • Pages: páginas de workspace e de projeto
  • Links: links e relações de work items
  • Workspace: operações no nível do workspace
  • Epics: gestão de épicos
  • Intake: formulário de intake e solicitações
  • Stickies: notas adesivas
  • Teamspaces: gestão de teamspaces
  • Milestones: acompanhamento de marcos
  • Initiatives: gestão de iniciativas
  • WorkspaceTemplates: templates de work item, projeto e página no nível do workspace
  • WorkspaceWorkItemTypes: tipos de work item do workspace, com vínculo de propriedades
  • WorkspaceWorkItemProperties: propriedades customizadas do workspace, com opções
  • WorkspaceProjectLabels: labels de projeto no nível do workspace
  • WorkspaceProjectStates: estados de projeto no nível do workspace
  • WorkItemRelationDefinitions: tipos de relação de work item customizados
  • Releases: releases com tags, labels, labels de item, changelog, comentários, links e work items
  • Collections: pastas que agrupam páginas do workspace, com gestão de membros e páginas
  • AgentRuns: orquestração de execuções de agentes de IA e acompanhamento de atividades
  • Workflows: fluxos de trabalho do projeto, com estados, transições, hooks de transição, atividades e aprovações de work items
  • ProjectTemplates: templates de work item e de página por projeto
  • Features: funcionalidades do workspace e do projeto
  • WorkspaceStates: estados de work item do catálogo do workspace, sob governança do workspace (leitura em dois modos, escrita só governada)
  • WorkspaceWorkflows: catálogo de fluxos de trabalho do workspace sob governança, com cadeia (estados), transições, uso, atividades e hooks de transição
  • WorkItemTypeGovernance: governa quais fluxos um tipo de work item do workspace pode usar (modos any, constrained e required), com fixação por projeto e os endpoints de escolha e prévia de fallback do projeto
  • Instance: configuração e metadados da instância (versão, edição, provedores de autenticação, SMTP, limites de upload), de GET /api/instances/

Os sub-recursos ficam no recurso pai: workItems.comments, workItems.attachments, workItems.activities, workItems.relations, workItems.workLogs, customers.properties, customers.requests, teamspaces.members, teamspaces.projects, initiatives.labels, initiatives.projects, initiatives.epics, agentRuns.activities, workItemProperties.options, workItemProperties.values e assim por diante.

Informações da instância​

const info = await client.instance.retrieve();
console.log(info.instance.current_version, info.config.is_smtp_configured);

Baixando anexos​

workItems.attachments.download resolve a URL assinada de um anexo e o baixa, sem enviar a chave de API ao host de armazenamento. Com maxBytes, um arquivo maior é recusado com AttachmentTooLargeError: de antemão, quando o armazenamento informa o Content-Length, ou assim que o corpo passa do limite.

import { AttachmentTooLargeError } from "@hoyasumii/plane";

try {
  const { data, contentType } = await client.workItems.attachments.download("acme", projectId, itemId, "asset-1", {
    maxBytes: 20 * 1024 * 1024,
  });
  console.log(contentType, data.length);
} catch (error) {
  if (error instanceof AttachmentTooLargeError) console.log("grande demais");
  else throw error;
}

Erros​

Uma requisição v1 que falha lança HttpError, com o status, o corpo da resposta e os headers da resposta (em minúsculas, então headers["retry-after"] num 429). Veja Erros para a hierarquia completa.