meta

package
v1.0.54 Latest Latest
Warning

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

 Go to latest Published: Jun 15, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package meta is the typed model of the API metadata registry and the single place that parses it. The metadata is a fixed, regular vocabulary, so a plain typed json.Unmarshal replaces hand-rolled map[string]interface{} walking. Map key order is not preserved (Go maps are unordered); callers that need a deterministic sequence get fields/methods/resources sorted by name via the list accessors below.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IdentityForToken 

func IdentityForToken(token Token) (string, bool)

IdentityForToken maps a metadata access token to the CLI identity (--as value) that uses it: tenant -> "bot", user -> "user". ok is false for unrecognized tokens. This is the single source of truth for the token<->identity vocabulary; schema, registry and command code all go through it instead of re-spelling the mapping.

Types

type Affordance 

type Affordance struct {
	UseWhen       []string         `json:"use_when,omitempty"`
	DoNotUseWhen  []string         `json:"do_not_use_when,omitempty"`
	Prerequisites []string         `json:"prerequisites,omitempty"`
	Examples      []AffordanceCase `json:"examples,omitempty"`
	Related       []string         `json:"related,omitempty"`
}

Affordance is the hand-authored usage guidance overlaid on a method: when to use it, when not to, prerequisites, few-shot examples, and related methods. It is the single typed model of the affordance shape; the envelope renderer and the command help both parse through ParsedAffordance so the vocabulary is defined once. The JSON tags double as the envelope's wire shape.

type AffordanceCase 

type AffordanceCase struct {
	Description string `json:"description"`
	Command     string `json:"command"`
}

AffordanceCase is one few-shot example: a one-line description and a ready-to-run command.

type EnumOption 

type EnumOption struct {
	Value       any
	Description string
}

EnumOption is one allowed value paired with its human description. The description comes from options[].description and is empty for the bare `enum` form (which carries no descriptions).

type Field 

type Field struct {
	Name        string           `json:"-"`
	Type        string           `json:"type"`
	Location    string           `json:"location"` // "path" | "query"; empty for body/response
	Required    bool             `json:"required"`
	Description string           `json:"description"`
	Default     any              `json:"default"`
	Example     any              `json:"example"`
	Min         string           `json:"min"`
	Max         string           `json:"max"`
	Enum        []any            `json:"enum"`
	Options     []Option         `json:"options"`
	Properties  map[string]Field `json:"properties"`
}

Field is one parameter or body/response field. Name is the parent map key, populated by the list accessors (not a JSON field). ref/annotations/enumName exist in the metadata but are intentionally not modeled (unused downstream).

func (Field) CanonicalType 

func (f Field) CanonicalType() string

CanonicalType maps meta_data's non-standard type names to the standard JSON-Schema/type vocabulary used downstream (envelope render, flag kinds): "file" -> "string", "list" -> "array"; other types pass through unchanged.

func (Field) Children 

func (f Field) Children() []Field

Children returns the field's nested properties sorted by name.

func (Field) CoercedDefault 

func (f Field) CoercedDefault() any

CoercedDefault returns Default coerced to the canonical type, or nil when the field has no default or the literal cannot be coerced.

func (Field) CoercedExample 

func (f Field) CoercedExample() any

CoercedExample returns Example coerced to the canonical type, or nil when the field has no example or the literal cannot be coerced.

func (Field) EnumOptions 

func (f Field) EnumOptions() []EnumOption

EnumOptions returns the field's allowed values paired with their descriptions — from enum, or from options when enum is absent — coerced to the canonical type and ordered: numeric and boolean values are sorted; string values keep source order (which can encode priority). Uncoercible literals are dropped. Returns nil when the field declares no enum constraint.

func (Field) EnumValues 

func (f Field) EnumValues() []any

EnumValues returns the field's allowed values — the value projection of EnumOptions, in the same order. nil when the field declares no enum constraint. (Kept as the values-only accessor for the envelope and flag completion, which don't need descriptions.)

func (Field) FlagName 

func (f Field) FlagName() string

FlagName is the kebab-case CLI flag for this field (chat_id -> chat-id).

func (Field) MaxBound 

func (f Field) MaxBound() *float64

MaxBound returns the field's max constraint as a number, or nil when absent or unparseable. See MinBound.

func (Field) MinBound 

func (f Field) MinBound() *float64

MinBound returns the field's min constraint as a number, or nil when absent or unparseable. meta_data carries min/max as strings and does not say whether they bound a value or a string's length; the accessors stay equally agnostic, so every renderer (envelope minimum/maximum, flag help) presents the same numbers without inventing a semantic the source doesn't declare.

type Method 

type Method struct {
	Name           string           `json:"-"`
	ID             string           `json:"id"`
	Path           string           `json:"path"`
	HTTPMethod     string           `json:"httpMethod"`
	Description    string           `json:"description"`
	Risk           string           `json:"risk"`
	DocURL         string           `json:"docUrl"`
	Danger         bool             `json:"danger"`
	Tips           []string         `json:"tips"`
	Scopes         []string         `json:"scopes"`
	RequiredScopes []string         `json:"requiredScopes"`
	AccessTokens   []Token          `json:"accessTokens"`
	Affordance     json.RawMessage  `json:"affordance"`
	Parameters     map[string]Field `json:"parameters"`
	RequestBody    map[string]Field `json:"requestBody"`
	ResponseBody   map[string]Field `json:"responseBody"`
}

Method is one API operation. Name is the parent map key. Affordance is kept raw so this package stays free of envelope concerns.

func FromMap 

func FromMap(method map[string]interface{}) Method

FromMap decodes a single method spec from its map form into a typed Method. Convenience constructor for building typed values from map literals (tests).

func (Method) Data 

func (m Method) Data() []Field

Data are the non-file request-body fields (--data JSON), sorted by name.

func (Method) Files 

func (m Method) Files() []Field

Files are the file-typed request-body fields (--file uploads), sorted by name.

func (Method) Identities 

func (m Method) Identities() []string

Identities returns the CLI identities (--as values) that can call this method, derived from its metadata accessTokens: tenant -> "bot", user stays "user"; unrecognized tokens are dropped; the result is deduped and name-sorted. The slice is always non-nil so callers rendering it (e.g. the envelope's access_tokens) emit [] rather than null.

An empty result does NOT imply unrestricted — use RestrictsIdentity() for that. Identities() lists only CLI-known identities, so a method restricted solely to unrecognized tokens returns empty yet RestrictsIdentity() is true.

func (Method) Params 

func (m Method) Params() []Field

Params are the path/query parameters, sorted by name.

func (Method) ParsedAffordance 

func (m Method) ParsedAffordance() (Affordance, bool)

ParsedAffordance decodes the method's raw affordance overlay into the typed Affordance. ok is false when the method carries no affordance, the JSON is malformed, or every section is empty — so callers can treat "no guidance" uniformly.

func (Method) Response 

func (m Method) Response() []Field

Response are the response-body fields, sorted by name.

func (Method) RestrictsIdentity 

func (m Method) RestrictsIdentity() bool

RestrictsIdentity reports whether the method limits which identities may call it: true exactly when it declares one or more accessTokens. nil OR an empty slice means unrestricted (any identity). This is the single rule that both the strict-mode predicate (SupportsToken) and command identity gates use, so nil and [] never diverge across schema/scope and execution.

func (Method) SupportsToken 

func (m Method) SupportsToken(token Token) bool

SupportsToken reports whether this method is reachable with the given access token (see TokenForIdentity). An unrestricted method (RestrictsIdentity == false, i.e. nil or empty accessTokens) is reachable by any token. This is the single source of truth for the predicate; registry scope policy and command identity checks build on it.

type Option 

type Option struct {
	Value       any    `json:"value"`
	Description string `json:"description"`
}

Option is one enum option of a field. Value is `any` (not string) so a metadata value that arrives as a JSON number — rather than the usual quoted string — coerces like Field.Enum / EnumOption.Value instead of failing the whole registry unmarshal and blanking the entire catalog. coerceLiteral normalizes it to the field's declared type.

type Registry 

type Registry struct {
	Services []Service `json:"services"`
	Version  string    `json:"version"`
}

Registry is the top-level metadata document.

func Parse 

func Parse(data []byte) (Registry, error)

Parse decodes the metadata JSON into the typed Registry. Returns a zero Registry for empty input.

type Resource 

type Resource struct {
	Name      string              `json:"-"`
	Methods   map[string]Method   `json:"methods"`
	Resources map[string]Resource `json:"resources"`
}

Resource groups methods (and may nest sub-resources). Name is the parent key.

func (Resource) Method 

func (r Resource) Method(name string) (Method, bool)

Method looks up one method by name with Name injected, or false if absent. Use this instead of indexing Methods directly so Name is never left empty.

func (Resource) MethodList 

func (r Resource) MethodList() []Method

MethodList returns the resource's methods, name-injected and sorted by name.

func (Resource) SubResources 

func (r Resource) SubResources() []Resource

SubResources returns nested resources, name-injected and sorted by name.

type Service 

type Service struct {
	Name        string              `json:"name"`
	Version     string              `json:"version"`
	Title       string              `json:"title"`
	Description string              `json:"description"`
	ServicePath string              `json:"servicePath"`
	Resources   map[string]Resource `json:"resources"`
}

Service is one API service. Name is a real JSON field (services is an array).

func ServiceFromMap 

func ServiceFromMap(svc map[string]interface{}) Service

ServiceFromMap decodes a service spec from its map form into a typed Service. Convenience constructor for building typed values from map literals (tests).

func (Service) Resource 

func (s Service) Resource(name string) (Resource, bool)

Resource looks up one (possibly dotted) resource by name with Name injected, or false if absent. Use this instead of indexing Resources directly.

func (Service) ResourceList 

func (s Service) ResourceList() []Resource

ResourceList returns the service's top-level resources, name-injected and sorted by name.

type Token 

type Token string

Token is the metadata accessTokens vocabulary: which token kind a method accepts. It is a distinct type so the two directions of the token<->identity mapping below cannot be swapped silently — a bare string compiles on either side of a string/string signature, a Token does not. The CLI identity vocabulary ("bot"/"user") already has a home in internal/core (core.Identity); meta is a leaf and must not import core, so the identity side stays a plain string here and is typed at the core boundary. 

const (
	TokenTenant Token = "tenant" // bot calls use tenant_access_token
	TokenUser   Token = "user"
)

func TokenForIdentity 

func TokenForIdentity(identity string) Token

TokenForIdentity is the inverse of IdentityForToken: "bot" -> TokenTenant; everything else (notably "user") maps to itself.

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.