api

package
v2.10.1 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package api is the thin driving adapter between the generated strict HTTP server (package apigen) and the engine. Every handler follows the same shape: convert the request, call exactly one engine method, convert the result or classify the error into a Problem-shaped response. No business logic lives here.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Handler

func Handler(e *engine.Engine) http.Handler

Handler returns the complete net/http handler for the API, mounted under no particular prefix (the caller mounts it at /api/v1), with no PDF printer.

func New

func New(e *engine.Engine, deps Deps) http.Handler

New returns the complete net/http handler for the API over the given engine and dependencies.

func ReportCSV added in v2.3.0

func ReportCSV(t reporting.Table) ([]byte, error)

ReportCSV writes a report as CSV, a header row first.

Types

type AgentTokens added in v2.5.0

type AgentTokens interface {
	Mint(ctx context.Context, label string, ttl time.Duration) (string, store.AgentGrant, error)
}

AgentTokens is the port POST /agents mints through: the authorization server that issues agents' tokens, which grants the signed-in person's agent and returns a token that carries the grant (docs/adr/0016).

type Deps

type Deps struct {
	Printer printer.Printer
	// Authorizer answers GET /session's canWrite; the middleware still
	// decides every request. AllowAll when nil.
	Authorizer auth.Authorizer
	// Reports answers /reports. Nil turns reporting off: the reports
	// answer 404.
	Reports reporting.Reporter
	// AgentTokens mints the tokens POST /agents returns: the authorization
	// server's, when Cartograph is one. Nil answers 404.
	AgentTokens AgentTokens
	// AgentsOn says agents are served over MCP, for the session to say.
	AgentsOn bool
}

Deps is what a Server needs beyond the engine.

type Server

type Server struct {
	Engine  *engine.Engine
	Printer printer.Printer
	Authz   auth.Authorizer
	// Reports answers /reports; nil when the deployment turned
	// reporting off (docs/adr/0014).
	Reports reporting.Reporter
	// AgentTokens mints pasteable agent tokens; nil where another stack
	// authorizes agents.
	AgentTokens AgentTokens
	// AgentsOn is whether agents are served over MCP.
	AgentsOn bool
}

Server implements apigen.StrictServerInterface over an *engine.Engine. Printer is the port a PDF goes through; nil means printer.None.

func (*Server) AcceptChangeSet added in v2.7.0

func (*Server) AcceptProposal added in v2.5.0

AcceptProposal makes the record a proposal proposed, as the caller.

func (*Server) AppendSeriesItem added in v2.3.0

func (s *Server) AppendSeriesItem(ctx context.Context, req apigen.AppendSeriesItemRequestObject) (apigen.AppendSeriesItemResponseObject, error)

AppendSeriesItem records one item of a series, such as a reading, and commits the manifest with it.

func (*Server) ApplyRef

ApplyRef includes one manifest, or many, in the live state. Many in one call, because one at a time was quadratic and felt it: the engine reloads and reindexes once for the batch.

func (*Server) ClassifyStructure added in v2.10.0

ClassifyStructure says what each piece is from its answers.

func (*Server) CloseChangeSet added in v2.7.0

func (*Server) CreateAgentToken added in v2.5.0

CreateAgentToken lets an agent act for the caller by a token they paste into its client.

func (*Server) DeclineProposal added in v2.5.0

DeclineProposal declines a proposal, as the caller.

func (*Server) DeleteManifest

DeleteManifest excludes a manifest from the live state (any kind).

func (*Server) DiscardWorking

PutWorking saves a manifest's working copy without creating a version (autosave). DiscardWorking throws away a staged draft. Nothing is returned: the caller reads the manifest back, and what comes back is whatever the vault holds — the saved file, or nothing if it was never saved.

func (*Server) DropChangeSetItem added in v2.7.0

func (*Server) ExportSemanticLayer added in v2.10.0

func (s *Server) ExportSemanticLayer(ctx context.Context, req apigen.ExportSemanticLayerRequestObject) (apigen.ExportSemanticLayerResponseObject, error)

ExportSemanticLayer writes the KPIs as a semantic layer in a syntax the deployment has an exporter for (TAXONOMY.md D57).

func (*Server) FromIdea added in v2.9.0

FromIdea is the sentence of an idea that answers each question a walk asks.

func (*Server) GetAgentFeed added in v2.6.0

GetAgentFeed returns the document to follow a person's agents on.

func (*Server) GetChangeSet added in v2.7.0

func (*Server) GetChangeSetDocument added in v2.9.0

func (s *Server) GetChangeSetDocument(ctx context.Context, req apigen.GetChangeSetDocumentRequestObject) (apigen.GetChangeSetDocumentResponseObject, error)

GetChangeSetDocument names a change set's live draft of a manifest, creating it on first use (docs/adr/0024).

func (*Server) GetChangeSetItem added in v2.7.0

func (*Server) GetCharterPdf

GetCharterPdf prints the charter of a project, programme or operation to PDF. A project prints its working copy when asked, otherwise its latest version, and its working copy when it has no version yet: somebody exporting a draft wants the draft, not a refusal.

func (*Server) GetComponents added in v2.9.0

GetComponents is the graph of components across the workspace, read as the change set named would leave it.

func (*Server) GetCyclePeriods added in v2.9.0

GetCyclePeriods lays out a reporting cycle's periods between two months, as the engine derives them (TAXONOMY.md D40).

func (*Server) GetDecisionModel added in v2.9.0

GetDecisionModel is whether a decision model is configured and ready.

func (*Server) GetGapChecks

GetProgrammeChecks mirrors the goal's shape rather than the project's: a flat list, no blocking count, because none of a programme's checks blocks anything.

func (*Server) GetGlossary added in v2.7.0

GetGlossary is every word of the taxonomy, defined plainly, in the order of work.

func (*Server) GetGraph added in v2.7.0

func (*Server) GetGuide added in v2.6.0

GetGuide returns how to define a kind well, as agents read it over MCP. The engine's guide already has the contract's shape, field for field.

func (*Server) GetKPIControlChart added in v2.10.0

GetKPIControlChart reads a KPI's readings as a control chart.

func (*Server) GetLineage added in v2.10.0

func (s *Server) GetLineage(ctx context.Context, req apigen.GetLineageRequestObject) (apigen.GetLineageResponseObject, error)

GetLineage draws a project's data lineage from its data as it is being edited and the workspace as the change set reads it.

func (*Server) GetLinkCandidates added in v2.9.0

GetLinkCandidates is what a link may join from one record, read as the change set named would leave the workspace.

func (*Server) GetOperationCharterHtml

GetOperationCharterHtml renders an operation as its service description.

func (*Server) GetOperationChecks

GetOperationChecks: the same flat, advisory shape as a programme's.

func (*Server) GetOrder added in v2.7.0

GetOrder is the order of work and how far the workspace has got.

func (*Server) GetPortfolioChecks added in v2.9.0

GetPortfolioChecks answers in the programme's shape: every check is advice read from other manifests (TAXONOMY.md D32).

func (*Server) GetPresenceDocument

func (s *Server) GetPresenceDocument(ctx context.Context, req apigen.GetPresenceDocumentRequestObject) (apigen.GetPresenceDocumentResponseObject, error)

GetPresenceDocument names the document that routes presence: a record's, or the one for screens not about one manifest.

func (*Server) GetProgrammeCharterHtml

GetProgrammeCharterHtml renders a programme as a document.

func (*Server) GetProjectDMAIC added in v2.10.0

GetProjectDMAIC says whether a project can be taken through DMAIC (TAXONOMY.md D58).

func (*Server) GetProjectSchedule added in v2.9.0

GetProjectSchedule is a project's milestones placed on time, read as the change set named would leave it.

func (*Server) GetProposal added in v2.6.0

GetProposal returns a proposal as its person reviews it.

func (*Server) GetReport added in v2.3.0

func (s *Server) GetReport(ctx context.Context, req apigen.GetReportRequestObject) (apigen.GetReportResponseObject, error)

GetReport answers a report from the deployment's reporter, as JSON or as CSV; 404 when reporting is off.

func (*Server) GetSession

func (s *Server) GetSession(ctx context.Context, _ apigen.GetSessionRequestObject) (apigen.GetSessionResponseObject, error)

GetSession says who this request acts as. canWrite is the authorizer's answer for a write with no particular manifest; the engine still decides every write on its own.

func (*Server) GetSharedDocument

func (s *Server) GetSharedDocument(ctx context.Context, req apigen.GetSharedDocumentRequestObject) (apigen.GetSharedDocumentResponseObject, error)

GetSharedDocument names a manifest's shared draft, creating it on first use (docs/adr/0007).

func (*Server) GetVault

GetVault returns the state manifest: what the live state includes.

func (*Server) GetWorking

GetWorking returns the working copy as last saved, decoded through the engine's codec, or 404 when the manifest has none.

func (*Server) GrantPerson added in v2.2.0

func (s *Server) GrantPerson(ctx context.Context, req apigen.GrantPersonRequestObject) (apigen.GrantPersonResponseObject, error)

func (*Server) IncludeChangeSetItem added in v2.7.0

func (*Server) ListAgentGrants added in v2.5.0

ListAgentGrants lists the agents people let act for them.

func (*Server) ListChangeSets added in v2.7.0

func (*Server) ListExcluded

ListExcluded lists every excluded manifest, newest first.

func (*Server) ListPeople added in v2.2.0

func (s *Server) ListPeople(ctx context.Context, _ apigen.ListPeopleRequestObject) (apigen.ListPeopleResponseObject, error)

func (*Server) ListProposals added in v2.5.0

ListProposals lists what agents proposed (docs/adr/0016): the caller's open ones by default, or every proposal on one manifest.

func (*Server) ListSnapshots

ListSnapshots returns every snapshot (version) across all kinds, newest first.

func (*Server) ListUnapplied

ListUnapplied lists manifests present but not in the live state.

func (*Server) MatchExisting added in v2.9.0

MatchExisting is the records of a kind that say what a text says.

func (*Server) MoveInChangeSet added in v2.9.0

func (*Server) PostSnapshot

PostSnapshot records an explicit version of a manifest's current content with a reason. Snapshots the working copy if one exists, otherwise the current version. The author is from Settings.spec.operator.

func (*Server) ProposeChangeSet added in v2.7.0

func (*Server) PutChangeSetItem added in v2.7.0

func (*Server) RecoverRef

RecoverRef re-includes an excluded manifest in the live state.

func (*Server) Relevant added in v2.9.0

Relevant is what in the workspace is relevant to a piece of work.

func (*Server) RemoveInChangeSet added in v2.9.0

func (*Server) RemovePerson added in v2.2.0

func (s *Server) RemovePerson(ctx context.Context, req apigen.RemovePersonRequestObject) (apigen.RemovePersonResponseObject, error)

func (*Server) ReopenChangeSet added in v2.7.0

func (*Server) RetitleChangeSet added in v2.7.0

func (*Server) RevokeAgentGrant added in v2.5.0

RevokeAgentGrant disconnects an agent at once.

func (*Server) StartChangeSet added in v2.7.0

func (*Server) StructureQuestions added in v2.10.0

StructureQuestions lists the questions that decide what each piece of work is (TAXONOMY.md D56).

func (*Server) Sync

func (s *Server) Sync(_ context.Context, _ apigen.SyncRequestObject) (apigen.SyncResponseObject, error)

Sync answers a request to the sync path that did not upgrade: the socket itself is served by the sync server, mounted ahead of this handler (cmd/cartograph).

func (*Server) Understand added in v2.9.0

Understand is what a typed text reads as, and what already says it.

Directories

Path Synopsis
Package apigen provides primitives to interact with the openapi HTTP API.
Package apigen provides primitives to interact with the openapi HTTP API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL