tree

Documentation

Overview

Package tree wraps Geni's family-graph endpoints — immediate-family, ancestors, and path-to. These walk the relationship graph rather than fetching a single resource, so they live in their own package rather than under profile/.

Index

• type Client
  • func NewClient(t *transport.Client) *Client
  • func (c *Client) Ancestors(ctx context.Context, profileId string, opts ...Option) (*FamilyResponse, error)
  • func (c *Client) Compare(ctx context.Context, profile1Id, profile2Id string) (*Comparison, error)
  • func (c *Client) ImmediateFamily(ctx context.Context, profileId string) (*FamilyResponse, error)
  • func (c *Client) PathTo(ctx context.Context, fromId, toId string, opts ...Option) (*PathToResponse, error)
• type Comparison
• type FamilyNodes
  • func (n FamilyNodes) Profile(id string) (*profile.Profile, error)
  • func (n FamilyNodes) ProfileIds() []string
  • func (n FamilyNodes) Union(id string) (*union.Union, error)
  • func (n FamilyNodes) UnionIds() []string
• type FamilyResponse
• type Option
  • func WithGenerations(n int) Option
  • func WithPathType(t PathType) Option
  • func WithRefresh(v bool) Option
  • func WithSearch(v bool) Option
  • func WithSkipEmail(v bool) Option
  • func WithSkipNotify(v bool) Option
• type PathRelation
• type PathStatus
• type PathToResponse
• type PathType

Types

type Client

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

Client wraps a transport.Client with the family-graph endpoints.

func NewClient

func NewClient(t *transport.Client) *Client

NewClient returns a tree Client backed by the supplied transport.

func (*Client) Ancestors

func (c *Client) Ancestors(ctx context.Context, profileId string, opts ...Option) (*FamilyResponse, error)

Ancestors fetches the ancestor graph rooted at profileId. WithGenerations controls depth; the Geni-documented maximum is 20 generations and values above that are clamped client-side.

Observed behavior on the Geni sandbox (test account, 2026-05-14):

• 403 (surfaced as transport.ErrAccessDenied) for freshly-created profiles, managed profiles, and hand-built parent→child chains.
• `me` as the path id returns 500 ("No action responded to me").
• Sibling endpoints (ImmediateFamily, PathTo) succeed against the same token on the same profiles.

The public docs do not describe an access rule for this endpoint, and Geni publishes no OAuth scope catalog beyond a `read_profile, write_profile` example in /platform/developer/help/oauth_intro.

func (*Client) Compare

func (c *Client) Compare(ctx context.Context, profile1Id, profile2Id string) (*Comparison, error)

Compare fetches the immediate-family graphs of both profiles in a single call. The returned Results slice has two entries, one per profile, in the order they were requested.

func (*Client) ImmediateFamily

func (c *Client) ImmediateFamily(ctx context.Context, profileId string) (*FamilyResponse, error)

ImmediateFamily fetches the one-hop family graph around profileId (parents, partners, children, siblings) as a FamilyResponse. The response's Nodes map is heterogeneous — use FamilyNodes.Profile and FamilyNodes.Union to decode individual entries.

func (*Client) PathTo

func (c *Client) PathTo(ctx context.Context, fromId, toId string, opts ...Option) (*PathToResponse, error)

PathTo fetches the kinship path between fromId and toId. The call is asynchronous on Geni's side: a PathStatusPending response means the server is still computing and the caller should back off and re-issue. Geni's path-to also has side effects (email + on-site notifications) unless suppressed via WithSkipEmail / WithSkipNotify.

type Comparison

type Comparison struct {
	Results []FamilyResponse `json:"results,omitempty"`
}

Comparison is the response shape of Client.Compare. Geni returns immediate-family graphs for both profiles in one call; each Results entry mirrors what Client.ImmediateFamily would return for one of the two profiles, in the order requested.

type FamilyNodes

type FamilyNodes map[string]json.RawMessage

FamilyNodes is the heterogeneous map of related entities returned by Geni's family-graph endpoints (immediate-family, ancestors). Keys are Geni-prefixed ids: "profile-..." or "union-...". Values are stored as raw JSON so callers decode lazily into profile.Profile or union.Union via the accessor methods — this also leaves room for future node kinds (event-, document-, ...) without breaking the map.

func (FamilyNodes) Profile

func (n FamilyNodes) Profile(id string) (*profile.Profile, error)

Profile decodes the node at id into a profile.Profile. It errors if id does not name a profile node in the map.

func (FamilyNodes) ProfileIds

func (n FamilyNodes) ProfileIds() []string

ProfileIds returns every map key with the "profile-" prefix.

func (FamilyNodes) Union

func (n FamilyNodes) Union(id string) (*union.Union, error)

Union decodes the node at id into a union.Union. It errors if id does not name a union node in the map.

func (FamilyNodes) UnionIds

func (n FamilyNodes) UnionIds() []string

UnionIds returns every map key with the "union-" prefix.

type FamilyResponse

type FamilyResponse struct {
	Focus *profile.Profile `json:"focus,omitempty"`
	Nodes FamilyNodes      `json:"nodes,omitempty"`
}

FamilyResponse is the shape returned by Geni's family-graph endpoints (immediate-family, ancestors). Focus is the profile the call was anchored on, embedded inline by the server. Related profiles and unions live in Nodes.

type Option

type Option func(*http.Request)

Option customises an outgoing request for the family-graph and path-to endpoints. Options only set the parameters they understand; passing an option to a method that doesn't honor it is harmless.

func WithGenerations

func WithGenerations(n int) Option

WithGenerations sets the generations query parameter on Client.Ancestors. Values ≤0 are a no-op; values >20 are clamped to 20 (the Geni-documented maximum).

func WithPathType

func WithPathType(t PathType) Option

WithPathType sets the path_type query parameter on Client.PathTo. An empty value is a no-op (Geni defaults to "closest").

func WithRefresh

func WithRefresh(v bool) Option

WithRefresh forces a recomputation of a path-to result. The flag is only emitted when v is true.

func WithSearch

func WithSearch(v bool) Option

WithSearch toggles the path-to search behavior. Geni defaults to true, so the parameter is only emitted when v is false (i.e. to opt out).

func WithSkipEmail

func WithSkipEmail(v bool) Option

WithSkipEmail suppresses the email notification path-to would otherwise send. Only emitted when v is true.

func WithSkipNotify

func WithSkipNotify(v bool) Option

WithSkipNotify suppresses the on-site notification path-to would otherwise send. Only emitted when v is true.

type PathRelation

type PathRelation struct {
	ID       string `json:"id,omitempty"`
	Relation string `json:"relation,omitempty"`
	NextId   string `json:"next_id,omitempty"`
}

PathRelation is one hop along a path-to result.

type PathStatus

type PathStatus string

PathStatus is the server-side computation status of a path-to call. Geni's path-to endpoint may return PathStatusPending for paths that have not been computed yet; the caller is expected to back off and re-issue the same request.

const (
	PathStatusPending    PathStatus = "pending"
	PathStatusDone       PathStatus = "done"
	PathStatusOverloaded PathStatus = "overloaded"
	PathStatusNotFound   PathStatus = "not found"
)

type PathToResponse

type PathToResponse struct {
	Relations    []PathRelation `json:"relations,omitempty"`
	Relationship string         `json:"relationship,omitempty"`
	Status       PathStatus     `json:"status,omitempty"`
}

PathToResponse is the shape returned by Client.PathTo. Status must be inspected before treating Relations as authoritative — a PathStatusPending response carries no relations.

type PathType

type PathType string

PathType is the value of the path_type query parameter on Client.PathTo.

const (
	PathTypeClosest PathType = "closest"
	PathTypeBlood   PathType = "blood"
	PathTypeInlaw   PathType = "inlaw"
)