Documentation
¶
Overview ¶
Package apitypes defines the JSON wire contract for the web SPA's /api/* endpoints. It is the single source of truth: the Go handlers (internal/web) marshal these structs, and tygo generates the TypeScript types from this file (internal/web/frontend/src/lib/api-types.ts) — so the front-end and back-end can't drift. It is a pure data package (no imports) so codegen stays trivial.
Index ¶
- type ActivityDay
- type ActivityEvent
- type ActivityResponse
- type Backlink
- type CreatedNote
- type GraphData
- type GraphLink
- type GraphNode
- type JournalDay
- type JournalResponse
- type MovedNote
- type NoteCard
- type NoteLink
- type NoteView
- type NotesGrid
- type NotesIndex
- type OrphansResponse
- type RawNote
- type SearchResponse
- type SearchResult
- type State
- type Tag
- type TagsResponse
- type Task
- type TaskGroup
- type TaskRef
- type TasksResponse
- type TreeNode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ActivityDay ¶
type ActivityDay struct {
Date string `json:"date"`
Events []ActivityEvent `json:"events"`
}
ActivityDay groups events under a calendar date.
type ActivityEvent ¶
type ActivityEvent struct {
When string `json:"when"`
Action string `json:"action"`
Kind string `json:"kind"`
Source string `json:"source"`
Title string `json:"title"`
URL string `json:"url,omitempty"`
}
ActivityEvent is one item in the activity feed (When is RFC3339).
type ActivityResponse ¶
type ActivityResponse struct {
Days []ActivityDay `json:"days"`
Sources []string `json:"sources"`
}
ActivityResponse is GET /api/activity.
type Backlink ¶
type Backlink struct {
Title string `json:"title"`
URL string `json:"url"`
Text string `json:"text"`
IsNote bool `json:"isNote"`
}
Backlink is one "Linked from" entry on a note page.
type CreatedNote ¶
CreatedNote is the result of POST /api/notes — the new note's stable handle and its URL, so the client can navigate straight to it.
type GraphData ¶
type GraphData struct {
Nodes []GraphNode `json:"nodes"`
Links []GraphLink `json:"links"`
Truncated bool `json:"truncated,omitempty"` // capped to the most-connected nodes (E4)
}
GraphData is GET /api/graph — the note↔note wikilink graph.
type GraphNode ¶
type GraphNode struct {
ID string `json:"id"`
Kind string `json:"kind"` // "note" | "task"
Title string `json:"title"`
URL string `json:"url"`
Folder string `json:"folder"`
Source string `json:"source"`
Tags []string `json:"tags"`
Deg int `json:"deg"`
}
GraphNode is one entity in the knowledge graph (Deg = link degree, for sizing).
type JournalDay ¶
type JournalDay struct {
Date string `json:"date"` // YYYY-MM-DD
Handle string `json:"handle"` // note handle, for the note view
}
JournalDay is one existing daily note (date + the note's stable handle).
type JournalResponse ¶
type JournalResponse struct {
Today string `json:"today"` // today's date in the server's local time
Folder string `json:"folder"` // subfolder daily notes live under (e.g. "journal")
Days []JournalDay `json:"days"` // existing daily notes, newest first
}
JournalResponse is GET /api/journal — the daily-notes index for the journal UI.
type MovedNote ¶ added in v0.6.0
type MovedNote struct {
Handle string `json:"handle"`
URL string `json:"url"`
Rel string `json:"rel"`
Updated int `json:"updated"`
}
MovedNote is the result of POST /api/notes/{handle}/move — the (unchanged) handle/URL, the new path relative to notes/, and how many [[links]] were rewritten to follow the move.
type NoteCard ¶ added in v0.6.0
type NoteCard struct {
Handle string `json:"handle"`
Title string `json:"title"`
URL string `json:"url"`
Folder string `json:"folder"` // "" for root
Tags []string `json:"tags,omitempty"`
Preview string `json:"preview,omitempty"` // first lines of the body, plain text
Updated string `json:"updated,omitempty"` // YYYY-MM-DD (updated, else created)
}
NoteCard is one note projected for the /notes grid view.
type NoteLink ¶
type NoteLink struct {
URL string `json:"url"`
Title string `json:"title"`
Path string `json:"path"`
}
NoteLink is a link to a note (sidebar index, search results, prev/next).
type NoteView ¶
type NoteView struct {
ID string `json:"id"`
Title string `json:"title"`
Folder string `json:"folder"`
File string `json:"file"`
Crumbs []string `json:"crumbs"`
Source string `json:"source"`
Created string `json:"created"`
Tags []string `json:"tags"`
BodyHTML string `json:"bodyHTML"`
Backlinks []Backlink `json:"backlinks"`
TaskRefs []TaskRef `json:"taskRefs"`
Prev *NoteLink `json:"prev,omitempty"`
Next *NoteLink `json:"next,omitempty"`
ETag string `json:"etag"`
}
NoteView is GET /api/notes/{handle} — the fully rendered note page.
type NotesGrid ¶ added in v0.6.0
NotesGrid is GET /api/notes/grid — every note as a card, plus the folder vocabulary for the filter.
type NotesIndex ¶
NotesIndex is GET /api/notes — the tree plus a flat index.
type OrphansResponse ¶
type OrphansResponse struct {
Notes []NoteLink `json:"notes"`
}
OrphansResponse is GET /api/orphans — notes with no links in or out.
type SearchResponse ¶
type SearchResponse struct {
Results []SearchResult `json:"results"`
Truncated bool `json:"truncated,omitempty"` // more matched than were returned
}
SearchResponse is GET /api/search.
type SearchResult ¶
type SearchResult struct {
URL string `json:"url"`
Title string `json:"title"`
Path string `json:"path"`
Kind string `json:"kind,omitempty"` // "" / "note" (default) | "task"
Snippet string `json:"snippet,omitempty"` // matching line (note body hits only)
}
SearchResult is one ranked search hit. Notes rank first (title matches, then body matches carrying the matching line as a snippet); tasks follow, flagged by Kind so the UI can badge them and link to the task list.
type State ¶
type State struct {
CanEdit bool `json:"canEdit"`
CSRF string `json:"csrf"` // echo as X-CSRF on writes; "" when read-only
Version string `json:"version"`
OpenCount int `json:"openCount"`
NoteCount int `json:"noteCount"`
Sources []string `json:"sources"`
Warning string `json:"warning,omitempty"` // non-empty when the store couldn't be fully read
}
State is GET /api/state — capabilities + headline counts for the shell.
type TagsResponse ¶
type TagsResponse struct {
Tags []Tag `json:"tags"`
}
TagsResponse is GET /api/tags.
type Task ¶
type Task struct {
ID string `json:"id"`
Text string `json:"text"`
Status string `json:"status"`
Due string `json:"due,omitempty"`
Source string `json:"source,omitempty"`
Project string `json:"project,omitempty"`
Tags []string `json:"tags,omitempty"`
Blocker string `json:"blocker,omitempty"`
}
Task is one todo.txt task projected for the UI.
type TaskRef ¶
type TaskRef struct {
Text string `json:"text"`
Status string `json:"status"`
Source string `json:"source"`
}
TaskRef is one task that references a note (the task↔note moat).
type TasksResponse ¶
type TasksResponse struct {
Groups []TaskGroup `json:"groups"`
}
TasksResponse is GET /api/tasks and the body returned by task writes.