workflowy

package
v0.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 18, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExpandTilde added in v0.6.0 

func ExpandTilde(path string) string

ExpandTilde expands a leading ~ to the user's home directory

func IsDescendantOf added in v0.7.1 

func IsDescendantOf(items []*Item, rootID, targetID string) bool

IsDescendantOf checks if targetID equals rootID or is a descendant of rootID.

func IsShortID added in v0.6.0 

func IsShortID(id string) bool

IsShortID returns true if the ID is exactly 12 hexadecimal characters

func IsTargetKey added in v0.6.0 

func IsTargetKey(ctx context.Context, client Client, id string) (bool, error)

IsTargetKey checks if the given ID matches a known target key

func IsWriteRestricted added in v0.7.1 

func IsWriteRestricted(writeRootID string) bool

IsWriteRestricted returns true if writeRootID represents an active restriction.

func LimitItemDepth added in v0.5.0 

func LimitItemDepth(item *Item, maxDepth int)

func LimitItemsDepth added in v0.5.0 

func LimitItemsDepth(items []*Item, depth int)

func ResolveAPIKey added in v0.6.0 

func ResolveAPIKey(apiKeyFile, defaultAPIKeyFile string) (client.Option, error)

ResolveAPIKey resolves the API key with precedence: 1. Explicit file path (if different from default) 2. WORKFLOWY_API_KEY environment variable 3. Default file path

func ResolveNodeID added in v0.6.0 

func ResolveNodeID(ctx context.Context, client Client, id string) (string, error)

ResolveNodeID resolves target keys, short IDs, and sanitizes full IDs. If client is nil, only sanitization is performed.

func ResolveNodeIDToUUID added in v0.7.1 

func ResolveNodeIDToUUID(ctx context.Context, client Client, id string) (string, error)

ResolveNodeIDToUUID resolves any node identifier to a full UUID. Unlike ResolveNodeID, this always returns a UUID even for target keys like "inbox".

func ResolveShortID added in v0.6.0 

func ResolveShortID(ctx context.Context, client Client, shortID string) (string, error)

ResolveShortID resolves a short ID to its full UUID by searching all nodes

func SanitizeNodeID added in v0.6.0 

func SanitizeNodeID(id string) string

SanitizeNodeID strips the Workflowy URL prefix if present, then removes any character that is not hexadecimal or a dash from a node ID

func ValidatePosition added in v0.7.0 

func ValidatePosition(position string) error

ValidatePosition validates that position is either empty, "top", or "bottom".

func ValidateWriteAccess added in v0.7.1 

func ValidateWriteAccess(items []*Item, writeRootID, targetID, operation string) error

ValidateWriteAccess returns an error if targetID is not within writeRootID scope.

func WithAPIKey 

func WithAPIKey(apiKey string) client.Option

WithAPIKey sets up Bearer token authentication

func WithAPIKeyFromFile 

func WithAPIKeyFromFile(filename string) (client.Option, error)

WithAPIKeyFromFile reads API key from file and sets up Bearer token authentication

Types

type BackupNode 

type BackupNode struct {
	ID         string                 `json:"id"`
	Name       string                 `json:"nm"`
	Note       *string                `json:"no,omitempty"`
	Children   []BackupNode           `json:"ch,omitempty"`
	CreatedAt  int64                  `json:"ct,omitempty"`
	ModifiedAt int64                  `json:"lm,omitempty"`
	Completed  *int64                 `json:"cp,omitempty"`
	Metadata   map[string]interface{} `json:"metadata,omitempty"`
}

BackupNode represents a node from a Workflowy backup file Backup files use different field names than the API (nm, ch, ct, lm)

type BackupProvider added in v0.4.0 

type BackupProvider interface {
	ReadBackupFile(filename string) ([]*Item, error)
	ReadLatestBackup() ([]*Item, error)
}
var DefaultBackupProvider BackupProvider = &FileBackupProvider{}

type ChildrenCountRankable 

type ChildrenCountRankable struct {
	Node *NodeWithTimestamps
}

ChildrenCountRankable implements ranking by children count

func RankByChildrenCount 

func RankByChildrenCount(nodes []*NodeWithTimestamps, topN int) []ChildrenCountRankable

RankByChildrenCount ranks nodes by their immediate children count

func (*ChildrenCountRankable) GetRankingValue 

func (r *ChildrenCountRankable) GetRankingValue() int

func (*ChildrenCountRankable) GetValue 

func (r *ChildrenCountRankable) GetValue() fmt.Stringer

func (ChildrenCountRankable) String 

func (r ChildrenCountRankable) String() string

type Client added in v0.4.0 

type Client interface {
	GetItem(ctx context.Context, itemID string) (*Item, error)
	ListChildren(ctx context.Context, itemID string) (*ListChildrenResponse, error)
	ListChildrenRecursive(ctx context.Context, itemID string) (*ListChildrenResponse, error)
	ListChildrenRecursiveWithDepth(ctx context.Context, itemID string, depth int) (*ListChildrenResponse, error)
	CreateNode(ctx context.Context, req *CreateNodeRequest) (*CreateNodeResponse, error)
	UpdateNode(ctx context.Context, itemID string, req *UpdateNodeRequest) (*UpdateNodeResponse, error)
	MoveNode(ctx context.Context, itemID string, req *MoveNodeRequest) (*MoveNodeResponse, error)
	CompleteNode(ctx context.Context, itemID string) (*UpdateNodeResponse, error)
	UncompleteNode(ctx context.Context, itemID string) (*UpdateNodeResponse, error)
	DeleteNode(ctx context.Context, itemID string) (*UpdateNodeResponse, error)
	ExportNodesWithCache(ctx context.Context, forceRefresh bool) (*ExportNodesResponse, error)
	ListTargets(ctx context.Context) (*ListTargetsResponse, error)
}

type CreateNodeRequest 

type CreateNodeRequest struct {
	ParentID   string  `json:"parent_id"`
	Name       string  `json:"name"`
	Note       *string `json:"note,omitempty"`
	LayoutMode *string `json:"layoutMode,omitempty"`
	Position   *string `json:"position,omitempty"`
}

CreateNodeRequest represents the request payload for nodes-create API

func (*CreateNodeRequest) SetPosition added in v0.7.0 

func (r *CreateNodeRequest) SetPosition(position string) error

SetPosition sets the position after validating it. Empty string is ignored (no position set).

type CreateNodeResponse 

type CreateNodeResponse struct {
	ItemID string `json:"item_id"`
}

CreateNodeResponse represents the response from nodes-create API

type Descendants 

type Descendants = *counter.DescendantTreeCount[**ItemNode]

Descendants is a type alias for descendant tree count

func CountDescendants 

func CountDescendants(item *Item, threshold float64) Descendants

CountDescendants counts descendants in a tree and returns filtered, sorted results

type ExportNode 

type ExportNode struct {
	ID          string                 `json:"id"`
	Name        string                 `json:"name"`
	Note        *string                `json:"note"`
	ParentID    *string                `json:"parent_id"`
	Priority    int                    `json:"priority"`
	Completed   bool                   `json:"completed"`
	Data        map[string]interface{} `json:"data"`
	CreatedAt   int64                  `json:"createdAt"`
	ModifiedAt  int64                  `json:"modifiedAt"`
	CompletedAt *int64                 `json:"completedAt"`
}

ExportNode represents a node from the export API with parent_id for tree reconstruction

type ExportNodesResponse 

type ExportNodesResponse struct {
	Nodes []ExportNode `json:"nodes"`
}

ExportNodesResponse represents the response from GET /nodes-export

type FileBackupProvider added in v0.4.0 

type FileBackupProvider struct{}

func (*FileBackupProvider) ReadBackupFile added in v0.4.0 

func (p *FileBackupProvider) ReadBackupFile(filename string) ([]*Item, error)

func (*FileBackupProvider) ReadLatestBackup added in v0.4.0 

func (p *FileBackupProvider) ReadLatestBackup() ([]*Item, error)

type GetItemResponse 

type GetItemResponse struct {
	Node Item `json:"node"`
}

GetItemResponse represents the response from GET /nodes/:id

type Item 

type Item struct {
	ID          string                 `json:"id"`
	Name        string                 `json:"name"`
	Note        *string                `json:"note"`
	Priority    int                    `json:"priority"`
	Data        map[string]interface{} `json:"data"`
	CreatedAt   int64                  `json:"createdAt"`
	ModifiedAt  int64                  `json:"modifiedAt"`
	CompletedAt *int64                 `json:"completedAt"`
	Children    []*Item                `json:"children,omitempty"`
}

Item represents a Workflowy item with all its properties

func BackupNodeToItem 

func BackupNodeToItem(node BackupNode) *Item

BackupNodeToItem converts a BackupNode to an Item recursively

func BuildTreeFromExport 

func BuildTreeFromExport(nodes []ExportNode) *Item

BuildTreeFromExport reconstructs a tree structure from flat export nodes Returns a root Item containing all top-level nodes as children

func ExportNodeToItem 

func ExportNodeToItem(node ExportNode) *Item

ExportNodeToItem converts an ExportNode to an Item

func FilterEmpty added in v0.5.0 

func FilterEmpty(items []*Item) []*Item

func FilterEmptyItem added in v0.5.0 

func FilterEmptyItem(item *Item) *Item

func FindItemByID added in v0.5.0 

func FindItemByID(items []*Item, id string) *Item

func FindItemInTree added in v0.5.0 

func FindItemInTree(items []*Item, targetID string, maxDepth int) *Item

func FindRootItem added in v0.5.0 

func FindRootItem(items []*Item, itemID string) *Item

func FlattenItem added in v0.5.0 

func FlattenItem(item *Item) []*Item

func ReadBackupFile 

func ReadBackupFile(filename string) ([]*Item, error)

ReadBackupFile reads and parses a Workflowy backup file

func ReadLatestBackup 

func ReadLatestBackup() ([]*Item, error)

ReadLatestBackup reads the most recent backup file from Dropbox folder

type ItemNode 

type ItemNode struct {
	// contains filtered or unexported fields
}

ItemNode wraps Item to implement counter.TreeProvider interface

func NewItemNode 

func NewItemNode(item *Item) *ItemNode

NewItemNode creates an ItemNode from an Item recursively

func (*ItemNode) Children 

func (n *ItemNode) Children() iter.Seq[counter.TreeProvider[*ItemNode]]

Children implements counter.TreeProvider

func (*ItemNode) ExternalURL 

func (n *ItemNode) ExternalURL() string

ExternalURL returns the external Workflowy URL for this item

func (*ItemNode) InternalURL 

func (n *ItemNode) InternalURL() string

InternalURL returns the internal Workflowy URL for this item

func (*ItemNode) Item added in v0.4.0 

func (n *ItemNode) Item() *Item

Item returns the underlying Item

func (*ItemNode) MarshalJSON 

func (n *ItemNode) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

func (*ItemNode) Name 

func (n *ItemNode) Name() string

Name returns the item's name

func (*ItemNode) Node 

func (n *ItemNode) Node() *ItemNode

Node implements counter.TreeProvider

func (*ItemNode) String 

func (n *ItemNode) String() string

String implements fmt.Stringer

type ListChildrenResponse 

type ListChildrenResponse struct {
	Items []*Item `json:"nodes"` // v1 API uses "nodes" field
}

ListChildrenResponse represents the response from list nodes API

func FilterEmptyList added in v0.5.0 

func FilterEmptyList(list *ListChildrenResponse) *ListChildrenResponse

func FlattenTree added in v0.5.0 

func FlattenTree(data interface{}) *ListChildrenResponse

type ListTargetsResponse added in v0.4.0 

type ListTargetsResponse struct {
	Targets []Target `json:"targets"`
}

ListTargetsResponse represents the response from GET /targets

type MoveNodeRequest added in v0.7.0 

type MoveNodeRequest struct {
	ParentID string  `json:"parent_id"`
	Position *string `json:"position,omitempty"`
}

MoveNodeRequest represents the request body for nodes-move API

func (*MoveNodeRequest) SetPosition added in v0.7.0 

func (r *MoveNodeRequest) SetPosition(position string) error

SetPosition sets the position after validating it. Empty string is ignored (no position set).

type MoveNodeResponse added in v0.7.0 

type MoveNodeResponse struct {
	Status string `json:"status"`
}

MoveNodeResponse represents the response from nodes-move API

type NodeWithTimestamps 

type NodeWithTimestamps struct {
	Count      Descendants
	Item       *Item
	CreatedAt  int64
	ModifiedAt int64
}

NodeWithTimestamps combines a descendant count node with timestamp information

func CollectNodesWithTimestamps 

func CollectNodesWithTimestamps(root Descendants) []*NodeWithTimestamps

CollectNodesWithTimestamps traverses the tree and collects all nodes with their timestamps

type Target added in v0.4.0 

type Target struct {
	Key  string  `json:"key"`
	Type string  `json:"type"`
	Name *string `json:"name"`
}

Target represents a Workflowy target (shortcuts or system targets)

type TimestampRankable 

type TimestampRankable struct {
	Node        *NodeWithTimestamps
	UseModified bool
}

TimestampRankable implements ranking by timestamp with formatting

func RankByCreated 

func RankByCreated(nodes []*NodeWithTimestamps, topN int) []TimestampRankable

RankByCreated ranks nodes by creation date (oldest first)

func RankByModified 

func RankByModified(nodes []*NodeWithTimestamps, topN int) []TimestampRankable

RankByModified ranks nodes by modification date (oldest first)

func (*TimestampRankable) GetRankingValue 

func (r *TimestampRankable) GetRankingValue() int

func (*TimestampRankable) GetValue 

func (r *TimestampRankable) GetValue() fmt.Stringer

func (TimestampRankable) String 

func (r TimestampRankable) String() string

type UpdateNodeRequest added in v0.2.0 

type UpdateNodeRequest struct {
	Name       *string `json:"name,omitempty"`
	Note       *string `json:"note,omitempty"`
	LayoutMode *string `json:"layoutMode,omitempty"`
}

UpdateNodeRequest represents the request body for nodes-update API

type UpdateNodeResponse added in v0.2.0 

type UpdateNodeResponse struct {
	Status string `json:"status"`
}

UpdateNodeResponse represents the response from nodes-update API

type WorkflowyClient 

type WorkflowyClient struct {
	*client.Client
	// contains filtered or unexported fields
}

WorkflowyClient wraps the generic Client with Workflowy-specific methods

func NewWorkflowyClient 

func NewWorkflowyClient(opts ...client.Option) *WorkflowyClient

NewWorkflowyClient creates a new Workflowy API client

func (*WorkflowyClient) CompleteNode added in v0.3.0 

func (wc *WorkflowyClient) CompleteNode(ctx context.Context, itemID string) (*UpdateNodeResponse, error)

func (*WorkflowyClient) CreateNode 

func (wc *WorkflowyClient) CreateNode(ctx context.Context, req *CreateNodeRequest) (*CreateNodeResponse, error)

CreateNode creates a new node in Workflowy

func (*WorkflowyClient) DeleteNode added in v0.4.0 

func (wc *WorkflowyClient) DeleteNode(ctx context.Context, itemID string) (*UpdateNodeResponse, error)

func (*WorkflowyClient) ExportNodes 

func (wc *WorkflowyClient) ExportNodes(ctx context.Context) (*ExportNodesResponse, error)

ExportNodes retrieves all nodes from Workflowy (rate limited to 1 req/min)

func (*WorkflowyClient) ExportNodesWithCache 

func (wc *WorkflowyClient) ExportNodesWithCache(ctx context.Context, forceRefresh bool) (*ExportNodesResponse, error)

ExportNodesWithCache retrieves all nodes using cache when valid forceRefresh bypasses cache and fetches fresh data

func (*WorkflowyClient) GetItem 

func (wc *WorkflowyClient) GetItem(ctx context.Context, itemID string) (*Item, error)

GetItem retrieves an item by ID from Workflowy

func (*WorkflowyClient) ListChildren 

func (wc *WorkflowyClient) ListChildren(ctx context.Context, itemID string) (*ListChildrenResponse, error)

ListChildren retrieves direct children of an item from Workflowy Use itemID "None" to get root level items

func (*WorkflowyClient) ListChildrenRecursive 

func (wc *WorkflowyClient) ListChildrenRecursive(ctx context.Context, itemID string) (*ListChildrenResponse, error)

ListChildrenRecursive retrieves children recursively, building a complete tree Use itemID "None" to get the entire outline tree Uses default depth of 5 levels

func (*WorkflowyClient) ListChildrenRecursiveWithDepth 

func (wc *WorkflowyClient) ListChildrenRecursiveWithDepth(ctx context.Context, itemID string, depth int) (*ListChildrenResponse, error)

ListChildrenRecursiveWithDepth retrieves children recursively up to specified depth Use itemID "None" to get the entire outline tree depth parameter controls how many levels deep to fetch (0 = no children, 1 = direct children only, etc.)

func (*WorkflowyClient) ListTargets added in v0.4.0 

func (wc *WorkflowyClient) ListTargets(ctx context.Context) (*ListTargetsResponse, error)

ListTargets retrieves all available targets (shortcuts and system targets)

func (*WorkflowyClient) MoveNode added in v0.7.0 

func (wc *WorkflowyClient) MoveNode(ctx context.Context, itemID string, req *MoveNodeRequest) (*MoveNodeResponse, error)

MoveNode moves a node to a new parent in Workflowy

func (*WorkflowyClient) UncompleteNode added in v0.3.0 

func (wc *WorkflowyClient) UncompleteNode(ctx context.Context, itemID string) (*UpdateNodeResponse, error)

func (*WorkflowyClient) UpdateNode added in v0.2.0 

func (wc *WorkflowyClient) UpdateNode(ctx context.Context, itemID string, req *UpdateNodeRequest) (*UpdateNodeResponse, error)

UpdateNode updates an existing node in Workflowy

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.