Zum Hauptinhalt springen

API v1

Die v1-Ressourcen hängen direkt am Client: client.projects, client.workItems, client.cycles und so weiter. Jeder arbeitsbereichsbezogene Aufruf nimmt zuerst den Arbeitsbereichs-Slug entgegen, dann die Projekt-ID, wo die URL eine hat. Anders als bei v2 ist project hier die UUID des Projekts, und die älteren Klassen buchstabieren die Löschmethode delete oder del (folge der Methodenliste, die dein Editor zeigt).

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>" });

// Ein Work Item über seinen lesbaren Schlüssel, im ganzen Workspace.
const byKey = await client.workItems.retrieveByIdentifier("workspace-slug", "ENG-12");

Ressourcen​

  • Projects: Projektverwaltung und -organisation
  • WorkItems: Verwaltung von Work Items mit vollständigen CRUD-Operationen
  • WorkItemTypes: Definition und Verwaltung benutzerdefinierter Work-Item-Typen
  • WorkItemProperties: Benutzerdefinierte Eigenschaften für Work Items
  • Labels: Kategorisierung und Verschlagwortung von Work Items
  • States: Verwaltung von Workflow-Status
  • Users: Benutzerverwaltung und Profile
  • Roles: Arbeitsbereichs- und Projektrollendefinitionen (nur lesend)
  • Estimates: Projektschätzungen und Schätzpunkte
  • Modules: Organisation von Funktionen und Modulverwaltung
  • Cycles: Sprint- und Iterationsverwaltung
  • Customers: Kundenverwaltung und -operationen
  • Pages: Verwaltung von Arbeitsbereichs- und Projektseiten
  • Links: Verknüpfung und Beziehungen von Work Items
  • Workspace: Operationen auf Arbeitsbereichsebene
  • Epics: Epic-Verwaltung und -organisation
  • Intake: Verwaltung von Intake-Formularen und -Anfragen
  • Stickies: Verwaltung von Stickies
  • Teamspaces: Teamspace-Verwaltung
  • Milestones: Meilenstein-Verfolgung und -verwaltung
  • Initiatives: Initiativenverwaltung
  • WorkspaceTemplates: Vorlagen für Work Items, Projekte und Seiten auf Arbeitsbereichsebene
  • WorkspaceWorkItemTypes: Verwaltung von Work-Item-Typen auf Arbeitsbereichsebene mit Eigenschaftsverknüpfungen
  • WorkspaceWorkItemProperties: Verwaltung benutzerdefinierter Eigenschaften auf Arbeitsbereichsebene mit Optionen
  • WorkspaceProjectLabels: Verwaltung von Projekt-Labels auf Arbeitsbereichsebene
  • WorkspaceProjectStates: Verwaltung von Projektstatus auf Arbeitsbereichsebene
  • WorkItemRelationDefinitions: Benutzerdefinierte Beziehungstypen für Work Items
  • Releases: Release-Verwaltung mit Tags, Labels, Element-Labels, Changelog, Kommentaren, Links und Work Items
  • Collections: Ordner, die Arbeitsbereichsseiten gruppieren, mit Mitglieder- und Seitenverwaltung
  • AgentRuns: Orchestrierung und Aktivitätsverfolgung von KI-Agentenläufen
  • Workflows: Projekt-Workflow-Verwaltung mit Status-Zuordnungen, Übergängen, Übergangs-Hooks, Aktivitäten und Work-Item-Freigaben
  • ProjectTemplates: Verwaltung von Work-Item- und Seitenvorlagen pro Projekt
  • Features: Verwaltung von Arbeitsbereichs- und Projektfunktionen
  • WorkspaceStates: Work-Item-Status auf Arbeitsbereichsebene (Katalog) unter Arbeitsbereichs-Governance — Dual-Mode-Lesen, nur gesteuertes Schreiben
  • WorkspaceWorkflows: Workflow-Katalog auf Arbeitsbereichsebene unter Arbeitsbereichs-Governance, mit Kette (Status), Übergängen, Nutzung, Aktivitäten und Übergangs-Hooks
  • WorkItemTypeGovernance: Steuert, welche Workflows ein Work-Item-Typ auf Arbeitsbereichsebene nutzen darf (any/constrained/required-Modi), mit projektweisen Pins und den projektseitigen Pick-/Fallback-Vorschau-Endpunkten
  • Instance: Instanzkonfiguration und -metadaten (Version, Edition, Auth-Provider, SMTP, Upload-Limits) von GET /api/instances/

Unterressourcen hängen an ihrem übergeordneten Element: 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 und so weiter.

Instanzinformationen​

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

Anhänge herunterladen​

workItems.attachments.download löst die signierte URL eines Anhangs auf und lädt ihn herunter, ohne den API-Schlüssel an den Speicher-Host zu senden. Mit maxBytes wird eine größere Datei verweigert, mit AttachmentTooLargeError: vorab, wenn der Speicher seine Content-Length ankündigt, sonst sobald der Body die Grenze überschreitet.

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;
}

Fehler​

Eine fehlgeschlagene v1-Anfrage löst HttpError aus, mit dem Statuscode, dem Antwortkörper und den Antwort-Headern (kleingeschrieben, sodass headers["retry-after"] bei einem 429 funktioniert). Siehe Fehler für die gesamte Hierarchie.