Saltar para o conteúdo principal

API v1

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

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 respetiva chave humana, em todo o workspace.
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 personalizados
  • WorkItemProperties: propriedades personalizadas de work items
  • Labels: categorização por labels
  • States: estados do fluxo de trabalho
  • Users: utilizadores e perfis
  • Roles: funções de workspace e de projeto (apenas leitura)
  • Estimates: estimativas de projeto e respetivos 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: ligações e relações de work items
  • Workspace: operações ao nível do workspace
  • Epics: gestão de épicos
  • Intake: formulário de intake e pedidos
  • Stickies: notas autocolantes
  • Teamspaces: gestão de teamspaces
  • Milestones: acompanhamento de marcos
  • Initiatives: gestão de iniciativas
  • WorkspaceTemplates: modelos de work item, projeto e página ao nível do workspace
  • WorkspaceWorkItemTypes: tipos de work item do workspace, com associação de propriedades
  • WorkspaceWorkItemProperties: propriedades personalizadas do workspace, com opções
  • WorkspaceProjectLabels: labels de projeto ao nível do workspace
  • WorkspaceProjectStates: estados de projeto ao nível do workspace
  • WorkItemRelationDefinitions: tipos de relação de work item personalizados
  • Releases: releases com tags, labels, labels de item, changelog, comentários, ligações 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: modelos 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 apenas governada)
  • WorkspaceWorkflows: catálogo de fluxos de trabalho do workspace sob governança, com cadeia (estados), transições, utilização, 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é-visualização de fallback do projeto
  • Instance: configuração e metadados da instância (versão, edição, fornecedores de autenticação, SMTP, limites de upload), a partir de GET /api/instances/

Os sub-recursos ficam agrupados nos respetivos recursos-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);

A transferir anexos​

workItems.attachments.download resolve o URL assinado de um anexo e transfere-o, sem enviar a chave de API ao host de armazenamento. Com maxBytes, um ficheiro maior é recusado com AttachmentTooLargeError: de imediato, quando o armazenamento anuncia o respetivo Content-Length, ou logo que o corpo ultrapasse o 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("too large");
  else throw error;
}

Erros​

Um pedido v1 falhado lança um HttpError, com o código de estado, o corpo da resposta e os cabeçalhos da resposta (em minúsculas, logo headers["retry-after"] num 429). Veja Erros para a hierarquia completa.