@kentcdodds/workflowy

Thin secret-backed helpers for the WorkFlowy REST API: targets, nodes, mirrors, and outline export.

AGENTS.md

58 lines · 2.3 KB · Markdown

@kentcdodds/workflowy — agent notes

Human intent and secret setup live in README.md. Import the package with kody:@kentcdodds/workflowy.

Named exports

Export	Use
`request`	Call an uncovered `/api/v1...` WorkFlowy endpoint with package auth/retry.
`listTargets`	List system targets and user shortcuts.
`listNodes` / `getNode`	List children of a parent, or fetch one node.
`createNode` / `updateNode` / `deleteNode`	Create, patch, or permanently delete a node.
`moveNode` / `completeNode` / `uncompleteNode`	Relocate or toggle completion.
`mirrorNode` / `deleteMirror`	Create a live mirror or remove a mirror root.
`exportNodes`	Flat export of all nodes (1 req/min).
`smokeTest`	Auth check via `listTargets`; returns a compact summary.
`getOverview`	Package identity, common actions, and operational notes.
default export	Dispatch any helper with `{ action, ...params }`; defaults to `overview`.

Smoke test

import workflowy from 'kody:@kentcdodds/workflowy'

export default async function main() {
	return await workflowy({ action: 'smokeTest' })
}

Or import the named export:

import { listTargets } from 'kody:@kentcdodds/workflowy'

export default async function main() {
	const response = await listTargets() as { targets?: Array<{ key?: string; type?: string }> }
	return {
		ok: true,
		targetCount: response.targets?.length ?? 0,
		keys: (response.targets ?? []).slice(0, 8).map((t) => t.key),
	}
}

Playbooks and edge cases

Prefer target keys (inbox, today, tomorrow, None) or full/short node ids for parent_id on list/create/move. Mirror parent_id must be a full existing node id — not inbox / calendar shortcuts / None.
Pass through name, note, layoutMode, position (top | bottom), and id as needed. Helpers stay thin and map camelCase (layoutMode, parentId) to API fields.
deleteNode is permanent. Prefer completeNode when the goal is marking done.
exportNodes is rate-limited to 1 request per minute and can return a large flat list — project results before returning them from execute.
Keep secret values and Authorization headers out of logs, errors, notes, and returned payloads. Refer to the secret only by name: WORKFLOWY_API_KEY.