hosted

package
v0.1.2 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrProjectIDUnavailable = errors.New("that Project identifier is already in use on this server")

ErrProjectIDUnavailable reports that the identifier a caller asked to reuse is already in use on that server. It is a sentinel because it is the one API failure a promotion has to tell apart from every other: it means either "this move already got this far" or "that identifier belongs to somebody else", and only the caller's own bootstrap can say which.

Functions

This section is empty.

Types

type AISettings

type AISettings struct {
	Judgment struct {
		Provider      string  `json:"provider"`
		Model         string  `json:"model"`
		BaseURL       *string `json:"baseUrl"`
		KeyConfigured bool    `json:"keyConfigured"`
		KeyHint       *string `json:"keyHint"`
	} `json:"judgment"`
	Embeddings struct {
		Provider      string  `json:"provider"`
		Model         string  `json:"model"`
		Dimensions    int     `json:"dimensions"`
		BaseURL       *string `json:"baseUrl"`
		KeyConfigured bool    `json:"keyConfigured"`
		KeyHint       *string `json:"keyHint"`
	} `json:"embeddings"`
	Effective struct {
		Judgment   string `json:"judgment"`
		Embeddings string `json:"embeddings"`
	} `json:"effective"`
	Revision  int       `json:"revision"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type APIError

type APIError struct {
	Status    int
	Code      string
	RequestID string
	Retryable bool
	// Message is the service's own sentence about what went wrong. Callers use
	// Code to decide; a member reads this.
	Message string
}

func (*APIError) Error

func (e *APIError) Error() string

Error prefers the service's sentence over the code.

This error reaches a member unchanged - the desktop shows it under the invite field, the CLI prints it - and "hosted API invite_expired (409)" tells them nothing they can act on when "That invite has expired. Ask for a new one." was already on the wire and was being discarded. Code is still what every programmatic decision is made on, including ClassifyCredentialError.

func (*APIError) Is added in v0.1.2

func (e *APIError) Is(target error) bool

Is lets errors.Is reach the sentinels above through the wrapped API error.

type BatchAck

type BatchAck struct {
	AcceptedEventIDs []string
	Cursor           string
}

type Bootstrap

type Bootstrap struct {
	DeviceID                     string
	SchemaMinimum, SchemaMaximum int
	Projects                     []Project
	Cursors                      map[string]string
}

type BriefItem

type BriefItem struct {
	ID              string `json:"id"`
	Kind            string `json:"kind"`
	Text            string `json:"text"`
	RelevanceReason string `json:"relevanceReason"`
	Fidelity        string `json:"fidelity"`
	AdvisoryAction  string `json:"advisoryAction"`
	Revision        int    `json:"revision"`
	Priority        int    `json:"priority"`
}

type ChangePage

type ChangePage struct {
	Items  []map[string]any
	Cursor string
}

type Client

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

func New

func New(rawBase, token string) (*Client, error)

func (*Client) AISettings

func (c *Client) AISettings(ctx context.Context, projectID string) (AISettings, error)

func (*Client) Bootstrap

func (c *Client) Bootstrap(ctx context.Context) (Bootstrap, error)

func (*Client) Collaboration

func (c *Client) Collaboration(ctx context.Context, projectID string) (CollaborationSnapshot, error)

func (*Client) CommentSyncCard

func (c *Client) CommentSyncCard(ctx context.Context, cardID, body string) (SyncComment, error)

func (*Client) CreateBrief

func (c *Client) CreateBrief(ctx context.Context, workstreamID, trigger, sinceCursor string, approximateTokenBudget int) (CoordinationBrief, error)

func (*Client) CreateDashboardTicket

func (c *Client) CreateDashboardTicket(ctx context.Context, projectID string) (DashboardTicket, error)

func (*Client) CreateInvite

func (c *Client) CreateInvite(ctx context.Context, projectID string, expiresInSeconds, maxUses int) (Invite, error)

func (*Client) CreateProject

func (c *Client) CreateProject(ctx context.Context, project NewProject) (Project, error)

func (*Client) CreateSyncCard

func (c *Client) CreateSyncCard(ctx context.Context, projectID, findingID, title, summary string) (SyncCard, error)

func (*Client) Enroll

func (c *Client) Enroll(ctx context.Context, inviteID, inviteSecret, deviceLabel, displayName, appVersion string) (Enrollment, error)

func (*Client) Heartbeat

func (c *Client) Heartbeat(ctx context.Context, workspaceID, state string) error

func (*Client) JoinProject

func (c *Client) JoinProject(ctx context.Context, inviteID, inviteSecret, deviceLabel, displayName, appVersion string) (Membership, error)

JoinProject redeems an invite as the already-enrolled device this client is authenticated as. Unlike Enroll it is authenticated, and it returns only the Project that was joined.

func (*Client) ProjectChanges

func (c *Client) ProjectChanges(ctx context.Context, projectID string) (ChangePage, error)

func (*Client) PublishBatch

func (c *Client) PublishBatch(ctx context.Context, batch []byte) (BatchAck, error)

func (*Client) PutAISettings

func (c *Client) PutAISettings(ctx context.Context, projectID string, write AISettingsWrite) (AISettings, error)

func (*Client) ResolveSyncCard

func (c *Client) ResolveSyncCard(ctx context.Context, cardID string, expectedRevision int, summary string, memberIDs, workstreamIDs []string) (Resolution, error)

func (*Client) RevokeDevice

func (c *Client) RevokeDevice(ctx context.Context, deviceID string) error

type CollaborationSnapshot

type CollaborationSnapshot struct {
	ProjectID   string       `json:"projectId"`
	SyncCards   []SyncCard   `json:"syncCards"`
	Resolutions []Resolution `json:"resolutions"`
	Cursor      string       `json:"cursor"`
}

type CoordinationBrief

type CoordinationBrief struct {
	BriefID         string      `json:"briefId"`
	ProjectID       string      `json:"projectId"`
	RepositoryID    string      `json:"repositoryId"`
	WorkstreamID    string      `json:"workstreamId"`
	GeneratedAt     string      `json:"generatedAt"`
	Trigger         string      `json:"trigger"`
	NextCursor      string      `json:"nextCursor,omitempty"`
	ContextRevision int         `json:"contextRevision"`
	RequestedBudget int         `json:"requestedBudget"`
	RenderedSize    int         `json:"renderedSize"`
	Truncated       bool        `json:"truncated"`
	Items           []BriefItem `json:"items"`
}

type CredentialStatus

type CredentialStatus string

CredentialStatus describes whether this device's stored credential is still accepted by the hosted API.

const (
	// CredentialOK means the credential authenticated successfully.
	CredentialOK CredentialStatus = "ok"
	// CredentialRevoked means a Project owner revoked this device. The member
	// cannot recover alone; they need a fresh invite.
	CredentialRevoked CredentialStatus = "revoked"
	// CredentialUnknown means the hosted API has no record of this credential.
	// It happens when the backing deployment was reset or restored, or when a
	// keychain entry outlived the account it belonged to.
	CredentialUnknown CredentialStatus = "unknown"
	// CredentialUncertain means the check could not complete - offline, timeout,
	// or a server fault. It must never be treated as a reason to reset anything.
	CredentialUncertain CredentialStatus = "uncertain"
)

func ClassifyCredentialError

func ClassifyCredentialError(err error) CredentialStatus

ClassifyCredentialError maps an error from any authenticated call onto a credential status. Both rejection codes arrive as HTTP 401, so the code - not the status - decides whether the member can recover on their own.

func (CredentialStatus) Recoverable

func (s CredentialStatus) Recoverable() bool

Recoverable reports whether a status means the local enrollment is dead and the member should be offered a reconnect.

type DashboardTicket

type DashboardTicket struct {
	Ticket    string
	ExpiresAt time.Time
}

type Enrollment

type Enrollment struct{ DeviceID, DeviceToken, DashboardTicket string }

type Invite

type Invite struct {
	ID, Secret string
	ExpiresAt  time.Time
}

type Membership

type Membership struct{ ProjectID, DashboardTicket string }

Membership is the result of joining another Project with the device credential this Mac already holds. It carries no device token, because no device was created: one Mac has one device identity across its Projects.

type NewProject added in v0.1.2

type NewProject struct {
	Label, DeviceLabel string
	// DisplayName is sent only when the member chose one; omitting it keeps the
	// device label as a seed the member is later asked to replace.
	DisplayName, AppVersion string
	// ID reuses an identifier this caller already holds instead of being issued
	// a new one. It is how a Project moves between deployments without changing
	// identity: the identifier is salted into every repository fingerprint and
	// stamped on every queued event envelope, so a Project that arrives on a new
	// server under a new identifier cannot be recognised as the same Project by
	// any of the evidence the device already holds. Empty means "issue one".
	ID string
}

NewProject is what a Project is created from. It is a struct rather than a run of string arguments because the fields are all strings and three of the five are optional, which is exactly the shape a positional call gets wrong silently.

type Project

type Project struct{ ID, Label string }

type Resolution

type Resolution struct {
	ID, SyncCardID, Summary, CreatedAt       string
	AffectedMemberIDs, AffectedWorkstreamIDs []string
	Revision                                 int
}

type SyncCard

type SyncCard struct {
	ID, FindingID, Title, Summary, State, UpdatedAt string
	Revision                                        int
	Comments                                        []SyncComment
	Resolution                                      *Resolution
}

type SyncComment

type SyncComment struct{ ID, MemberName, Body, CreatedAt string }

Jump to

Keyboard shortcuts

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