allisall

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

README

allisall-go

The Go client for the allisall API: a typed client covering events, imports, clients, agents, value models, outcome types, costs, analytics, calculations, reports, the dashboard and the health check. It needs Go 1.26 or later and imports nothing outside the standard library.

Install

go get github.com/All-is-AI/allisall-go

import "github.com/All-is-AI/allisall-go"

The package name is allisall.

Create a client

The client reads your API key from AIA_API_KEY:

export AIA_API_KEY=aia_...

client, err := allisall.NewClient()
if err != nil {
	log.Fatal(err)
}

A Client holds no mutable state after construction and is safe for concurrent use.

Call the API

The client groups its methods by resource, each a field of the client: Events, Imports, Clients, Agents, ValueModels, OutcomeTypes, Cost, Analytics, Calculations, Reports, Dashboard and Health. Every method takes a context.Context first, then the ids in its path, then its body or query, then options. Each method's documentation names the API operation it calls and the scope your key needs.

package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	"github.com/All-is-AI/allisall-go"
)

func main() {
	client, err := allisall.NewClient()
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	created, err := client.Clients.Create(ctx, allisall.ClientCreate{
		Name:      "Acme Logistics",
		Status:    allisall.ClientStatusActive,
		ClientKey: new("acme"),
	})
	var apiErr *allisall.APIError
	if errors.As(err, &apiErr) {
		log.Fatalf("the API refused the request: %d %s (request %s)",
			apiErr.Status, apiErr.Code, apiErr.RequestID)
	}
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("created", created.ID)
}

A call that creates something sends an Idempotency-Key, and sends the same key again on a retry, so a retry never creates a second one. Pass allisall.WithIdempotencyKey(key) to choose the key yourself, for example to make a create safe to repeat after your process restarts.

Update with a merge patch

An update sends only what you set. A field you leave at its zero value keeps its stored value. A field that can be cleared is an allisall.Nullable: allisall.NewNullable(v) sets it, allisall.Null clears it, and the zero Nullable leaves it unchanged.

updated, err := client.Clients.Update(ctx, clientID, allisall.ClientPatch{
	Status:      new(allisall.ClientStatusChurned),
	Notes:       allisall.Null[string](),           // clears the notes
	RenewalDate: allisall.NewNullable("2026-12-31"), // sets the renewal date
})

Lists

A list method sends the first request when you call it, and returns the first page. All walks every item of that page and of each page after it, fetching each page as the loop reaches it:

page, err := client.Agents.List(ctx, nil)
if err != nil {
	return err
}
for agent, err := range page.All(ctx) {
	if err != nil {
		return err
	}
	fmt.Println(agent.AgentKey, agent.Name)
}

To work a page at a time, read the page's Data, and move on with HasNextPage and NextPage. Body holds the whole response, such as the event list's Total:

page, err := client.Clients.List(ctx, &allisall.ListClientsParams{Limit: new(50)})
for err == nil {
	fmt.Println(len(page.Data), "clients")
	if !page.HasNextPage() {
		break
	}
	page, err = page.NextPage(ctx)
}
if err != nil {
	return err
}

Send events

package main

import (
	"context"
	"errors"
	"log"
	"time"

	"github.com/All-is-AI/allisall-go"
)

func main() {
	// Reads the API key from AIA_API_KEY.
	client, err := allisall.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	events := []allisall.EventInput{
		{
			Timestamp: time.Now(),
			AgentKey:  "support-bot",
			ClientKey: "contoso",
			Category:  allisall.EventCategoryModel,
			EventType: "completion",
			Model:     "gpt-4o",
			Cost:      new(allisall.MustParseDecimal("0.3683")),
			TokensIn:  new(int64(1200)),
			TokensOut: new(int64(350)),
		},
	}

	summary, err := client.Events.Ingest(context.Background(), events)
	var ingestErr *allisall.IngestError
	if errors.As(err, &ingestErr) {
		log.Fatalf("stopped at event %d: %v", ingestErr.RemainingFrom, err)
	}
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("accepted %d, duplicates %d, rejected %d",
		summary.Accepted, summary.Duplicates, summary.Rejected)
	for _, row := range summary.Errors {
		log.Printf("event %d: %s at %s: %s", row.Index, row.Code, row.Pointer, row.Detail)
	}
}

Ingest takes any number of events. It sends them in batches of at most 500 events and 4,000,000 bytes, one batch after another, and returns one summary for the whole list. A refused event does not fail the call: it is counted in Rejected, and each of its problems is an entry of Errors, whose Index is the event's position in your list. The API lists at most 20 problems of one event, and at most 1,000,000 bytes of entries for one batch. When either limit leaves entries out, ErrorsTruncated is true, and a refused event may have no entry; the counts still cover every event.

An event too large to send in any batch, more than 3,999,987 bytes as JSON, is not sent. It is reported in the summary as a rejected row with code too_large, and the other events are sent.

Ingest takes an API key only. A session token is refused with 401 unauthenticated.

Event ids and redelivery

Every event without an EventID is given a random one before it is first sent. A batch that is retried therefore never stores an event twice: an event the first attempt stored comes back counted as a duplicate.

That id lasts only for the call. If your own delivery is at-least-once, such as a queue that can redeliver a message, set EventID yourself, for example to the message's id. Otherwise an event delivered twice is sent twice with two different ids, and stored twice.

When a batch fails

Ingest stops at the first batch that fails, and sends nothing after it. It returns an *allisall.IngestError holding:

  • Summary: the outcome of the batches that succeeded;
  • Remaining: every event from the failed batch onward, each with the EventID it was given;
  • RemainingFrom: the position in your list of the first event in Remaining;
  • the cause, reachable with errors.As or errors.Is.

To recover, send Remaining again. Any event the failed batch stored before its response was lost comes back as a duplicate.

Import a CSV file

Imports.Preview reports what an import would store, and stores nothing. Imports.Commit stores the file's valid rows. Both take the mapping from your columns to event members, and the file as an io.ReadSeeker, such as an *os.File:

f, err := os.Open("events.csv")
if err != nil {
	return err
}
defer f.Close()
result, err := client.Imports.Commit(ctx, allisall.ImportUpload{
	Mapping: allisall.ImportMapping{
		Columns: &map[string]string{
			"timestamp":  "Time",
			"agent_key":  "Agent",
			"category":   "Category",
			"event_type": "Type",
		},
		Timezone: new("Asia/Tokyo"),
	},
	File: f,
})

The file is read again from the same position for each retry, so it is never held in memory.

Money

An amount of money is an allisall.Decimal, which holds the exact amount and never passes through a binary float. Write one from text:

cost, err := allisall.ParseDecimal("12.50")      // from text
cost = allisall.MustParseDecimal("0.3683")       // a constant in source
cost, err = allisall.DecimalFromFloat(0.3683)    // from a float64

DecimalFromFloat writes the shortest text that reads back as the same number, which is the literal you wrote for any value of up to 15 significant digits. The API takes at most 6 decimal places.

An amount the API returns is a Decimal too, with every digit the API sent. Its String method gives the exact text, and a Decimal you read can be sent back unchanged:

table, err := client.Cost.GetPriceTable(ctx)
if err != nil {
	return err
}
for _, rate := range table.Models {
	fmt.Println(rate.Model, rate.InputPer1K.String(), table.Currency)
}

Errors

An error from NewClient, and every error from sending a request, matches errors.Is(err, allisall.ErrAllisall). Reach the details with errors.As:

Type When
*allisall.APIError The API answered with an error status. Code names the error; Problem holds the whole problem document
*allisall.ConnectionError No response arrived, after any retries: the connection failed or the attempt timed out. RequestID is the id the client sent
*allisall.IngestError A batch failed inside Ingest. It wraps one of the two above, the context's error, or your token provider's error

Branch on APIError.Code. The API may add codes, and the SDK keeps a code it does not list as it arrived, so fall back on APIError.Status for a code you do not recognise. Quote RequestID when you report a problem.

err = client.Clients.Delete(ctx, clientID)
var apiErr *allisall.APIError
if errors.As(err, &apiErr) && apiErr.Code == allisall.ErrorCodeClientHasEvents {
	// Events carry the client's key, so mark the client churned instead.
	_, err = client.Clients.Update(ctx, clientID, allisall.ClientPatch{
		Status: new(allisall.ClientStatusChurned),
	})
}

A mistake in your own values is an ordinary error, which does not match ErrAllisall and fails the same way on every run. Nothing is sent. These include a path id that is empty, . or ..; text that is not valid UTF-8 in a body; a header option the SDK refuses, such as one it sets itself, or an Idempotency-Key it cannot send; an import file that cannot seek; an event Ingest cannot encode as JSON, such as a NaN Quantity; text ParseDecimal refuses; and a NaN or infinity passed to DecimalFromFloat. An error your token provider returns reaches you unchanged, and is not retried.

Retries

The client retries a failed attempt up to twice when no response arrived, or when the response is 408, 429, 500, 502, 503 or 504. Any other error status is returned at once.

It retries only a request that is safe to send again: a GET, PUT or DELETE; ingest, whose event ids deduplicate; and a call that sends an Idempotency-Key, which is every create and an import's commit. Such a call is also retried on a 409 idempotency_key_in_use, which means an earlier attempt with the same key is still running. A PATCH, an import preview, and ValueModels.SetLineItemsForClient are never retried. Setting line items is guarded by the model's Version, which refuses a repeat of a write that already landed; after a network error, read the model again before you retry.

Before a retry the client waits for the response's Retry-After. Without one, it waits about 0.5 seconds before the first retry and about 1 second before the second, with random jitter. When Retry-After asks for more than 60 seconds, the client does not retry: it returns the error, whose RetryAfter holds the wait, so you can decide.

A DELETE retried after a lost response can answer 404 for a delete that succeeded.

Configuration

NewClient takes these options:

Option Default
WithAPIKey(key) AIA_API_KEY from the environment
WithTokenProvider(func(ctx) (string, error)) None
WithBaseURL(url) AIA_BASE_URL from the environment, then https://api.allisai.ai
WithTimeout(d), per attempt 60 seconds
WithMaxRetries(n) 2
WithHTTPClient(*http.Client) A new http.Client
WithHeader(name, value), on every request None

NewClient resolves the credential once. Pass an API key or a token provider, not both. Without either it reads AIA_API_KEY, and fails when that is unset or empty. A token provider is called before every attempt, retries included.

The timeout bounds each attempt. Bound the whole call, retries and waits included, with the context you pass to the method.

Each method also takes options for that one call:

Option Effect
WithRequestTimeout(d) The timeout of each attempt of this call
WithRequestMaxRetries(n) The retries of this call. It cannot make a request the client never retries eligible
WithRequestHeader(name, value) One header for this call, over the client's WithHeader
WithIdempotencyKey(key) The Idempotency-Key of a create or an import's commit. Other methods do not accept it 
agents, err := client.Agents.List(ctx, nil,
	allisall.WithRequestTimeout(10*time.Second),
	allisall.WithRequestMaxRetries(0),
)

Sessions

A token provider may return a signed-in user's session token instead of an API key. Every method but Events.Ingest accepts one, and acts as that user. The client calls the provider before every attempt, so a refreshed token is picked up:

client, err := allisall.NewClient(allisall.WithTokenProvider(
	func(ctx context.Context) (string, error) {
		// In an application, return the signed-in user's current token
		// from your sign-in library.
		return os.Getenv("AIA_SESSION_TOKEN"), nil
	},
))

Validating, publishing and reopening a calculation, sharing and revoking a report, and managing API keys need a signed-in user, and this SDK does not offer them.

Documentation

See https://docs.allisai.ai.

License

Apache License 2.0. See LICENSE.

Documentation

Overview

Package allisall is the Go client for the allisall API.

A Client, built with NewClient, groups its methods by resource, each a field of the client: Events, Imports, Clients, Agents, ValueModels, OutcomeTypes, Cost, Analytics, Calculations, Reports, Dashboard and Health. Every method takes a context first, then the ids in its path, then its body or query, then options for that one call. 

client, err := allisall.NewClient() // reads AIA_API_KEY
if err != nil {
	return err
}
detail, err := client.Clients.Get(ctx, clientID)

EventsService.Ingest sends any number of events in as many batches as the API's limits require, and reports one combined IngestSummary.

A list method returns the first Page; Page.All walks every item of every page. An update is a merge patch: a field left at its zero value is not sent, and a Nullable field is cleared with Null. Amounts of money are a Decimal, exact in both directions.

A request that is safe to send again is retried, twice by default: a GET, PUT or DELETE, ingest, and a create or an import's commit, which send one Idempotency-Key on every attempt. A PATCH, an import's preview and ValueModelsService.SetLineItemsForClient are never retried.

An error from NewClient, and every error from sending a request, matches errors.Is(err, allisall.ErrAllisall). The concrete types are *APIError, *ConnectionError and *IngestError; reach their fields with errors.As, and branch on APIError.Code. A mistake in the caller's own values is an ordinary error that does not match ErrAllisall, and nothing is sent. Such mistakes include a path id that is empty, . or ..; a header option the SDK refuses, such as one it sets itself, or an Idempotency-Key it cannot send; an event Ingest cannot encode as JSON; text ParseDecimal refuses; and a non-finite number passed to DecimalFromFloat.

The credential is an API key or a token provider set with WithTokenProvider. A provider may return a signed-in user's session token, which every method but Ingest accepts.

A Client holds no mutable state after construction and is safe for concurrent use.

Index

Constants

View Source 
const (
	ImportDelimiterComma     = ","
	ImportDelimiterSemicolon = ";"
	ImportDelimiterTab       = "\t"
)

The field delimiters a CSV import's ImportMapping may name. The API reads a comma when Delimiter is nil.

Variables

View Source 
var ErrAllisall = errors.New("allisall")

ErrAllisall is the base of every SDK error. errors.Is(err, ErrAllisall) holds for an *APIError, a *ConnectionError, an *IngestError, and an error from NewClient.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	// Status is the HTTP status.
	Status int
	// Code is the problem's code. It is empty when the body was not a
	// problem document.
	Code ErrorCode
	// Problem is the whole problem document, or nil when the body was not
	// one.
	Problem *Problem
	// RequestID is the problem's request_id or, when there is no problem,
	// the response's X-Request-Id.
	RequestID string
	// RetryAfter is the wait the response's Retry-After asked for,
	// measured from when the response arrived. It is zero when the
	// response carried none, or one that does not parse or names a time
	// in the past. A Retry-After of 0 also reads as zero; the API itself
	// never sends less than 1.
	RetryAfter time.Duration
	// Headers are the response headers.
	Headers http.Header
	// contains filtered or unexported fields
}

APIError is an error response from the API, or a successful response whose body is not the shape the operation documents.

Branch on Code. For a code you do not recognise, fall back on Status.

func (*APIError) Error 

func (e *APIError) Error() string

Error describes the error.

func (*APIError) Is 

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

Is reports whether target is ErrAllisall.

type Agent added in v0.2.0 

type Agent struct {
	// AgentKey The external identity events carry. Immutable through this API.
	AgentKey  string    `json:"agent_key"`
	CreatedAt time.Time `json:"created_at"`

	// Framework Free text, `""` when empty.
	Framework string `json:"framework"`
	ID        string `json:"id"`

	// Name Free text.
	Name string `json:"name"`

	// Status An agent's lifecycle status.
	Status AgentStatus `json:"status"`

	// Version Free text, `""` when empty.
	Version string `json:"version"`
}

Agent An agent: a registry entry for something that delivers value. Ingest creates agents it has not seen.

type AgentCostLine added in v0.2.0 

type AgentCostLine struct {
	AgentID     string  `json:"agent_id"`
	AgentName   string  `json:"agent_name"`
	Manual      Decimal `json:"manual"`
	PassThrough Decimal `json:"pass_through"`
	TokenValued Decimal `json:"token_valued"`
	Total       Decimal `json:"total"`
}

AgentCostLine One agent's share of the cost.

type AgentCreate added in v0.2.0 

type AgentCreate struct {
	// AgentKey 1 to 200 characters, counted as sent. Not trimmed: a key with white space (the Unicode `White_Space` property) at either end, or white space only, is refused with `invalid_format`. Unique in the workspace. Cannot change later.
	AgentKey  string  `json:"agent_key"`
	Framework *string `json:"framework,omitempty"`

	// Name Free text, trimmed of white space (the Unicode `White_Space` property) at both ends. The trimmed name is stored. It holds 1 to 200 characters, counted in Unicode code points after trimming: blank after trimming is `required`, and longer than 200 characters after trimming is `too_long`. U+0000 is `invalid_format`, as in every request string. No JSON Schema keyword measures a length after trimming, so the schema states no `maxLength`; a `maxLength` of 200 would refuse a padded name the server accepts.
	Name string `json:"name"`

	// Status An agent's lifecycle status.
	Status  AgentStatus `json:"status"`
	Version *string     `json:"version,omitempty"`
}

AgentCreate defines model for AgentCreate.

type AgentDetail added in v0.2.0 

type AgentDetail struct {
	// AgentKey The external identity events carry. Immutable through this API.
	AgentKey string `json:"agent_key"`

	// Clients The clients the agent is assigned to, ordered by name, case-insensitively, then by id. At most 1,000: `clients_omitted` counts the rest.
	Clients []struct {
		ID   string `json:"id"`
		Name string `json:"name"`

		// Status A client's lifecycle status.
		Status ClientStatus `json:"status"`
	} `json:"clients"`

	// ClientsOmitted How many clients `clients` leaves out, `0` when it lists every one.
	ClientsOmitted int       `json:"clients_omitted"`
	CreatedAt      time.Time `json:"created_at"`

	// Framework Free text, `""` when empty.
	Framework string `json:"framework"`
	ID        string `json:"id"`

	// Name Free text.
	Name string `json:"name"`

	// Stats The agent's activity over the `from`/`to` range of the request, or all time.
	Stats AgentStats `json:"stats"`

	// Status An agent's lifecycle status.
	Status AgentStatus `json:"status"`

	// Version Free text, `""` when empty.
	Version string `json:"version"`
}

AgentDetail An agent with its assigned clients and statistics, as the single read returns it.

type AgentList added in v0.2.0 

type AgentList struct {
	// Data One page of items, at most `limit`, in the documented order.
	Data []AgentListItem `json:"data"`

	// HasMore Whether another page exists.
	HasMore    bool    `json:"has_more"`
	NextCursor *string `json:"next_cursor"`
}

AgentList Agents, ordered by name case-insensitively, then id. Includes agents ingest created.

type AgentListItem added in v0.2.0 

type AgentListItem struct {
	// AgentKey The external identity events carry. Immutable through this API.
	AgentKey string `json:"agent_key"`

	// ClientCount How many clients the agent is assigned to.
	ClientCount int       `json:"client_count"`
	CreatedAt   time.Time `json:"created_at"`

	// Framework Free text, `""` when empty.
	Framework string `json:"framework"`
	ID        string `json:"id"`

	// Name Free text.
	Name string `json:"name"`

	// Status An agent's lifecycle status.
	Status AgentStatus `json:"status"`

	// Version Free text, `""` when empty.
	Version string `json:"version"`
}

AgentListItem An agent as the list returns it.

type AgentPatch added in v0.2.0 

type AgentPatch struct {
	Framework Nullable[string] `json:"framework,omitzero"`

	// Name Free text, trimmed of white space (the Unicode `White_Space` property) at both ends. The trimmed name is stored. It holds 1 to 200 characters, counted in Unicode code points after trimming: blank after trimming is `required`, and longer than 200 characters after trimming is `too_long`. U+0000 is `invalid_format`, as in every request string. No JSON Schema keyword measures a length after trimming, so the schema states no `maxLength`; a `maxLength` of 200 would refuse a padded name the server accepts.
	Name *string `json:"name,omitempty"`

	// Status An agent's lifecycle status.
	Status  *AgentStatus     `json:"status,omitempty"`
	Version Nullable[string] `json:"version,omitzero"`
}

AgentPatch A JSON Merge Patch (RFC 7396). `agent_key` is refused with the field code `immutable`, not `unknown_field`: it exists, and this operation cannot change it.

type AgentStats added in v0.2.0 

type AgentStats struct {
	// CostTotal The sum of event `cost` in the requested range, rounded to `minor_units`.
	CostTotal Decimal `json:"cost_total"`
	Currency  string  `json:"currency"`

	// Events Events from this agent in the requested range.
	Events int `json:"events"`

	// MinorUnits The scale `cost_total` is rounded to.
	MinorUnits int `json:"minor_units"`
}

AgentStats The agent's activity over the `from`/`to` range of the request, or all time.

type AgentStatus added in v0.2.0 

type AgentStatus string

AgentStatus An agent's lifecycle status. 

const (
	AgentStatusActive  AgentStatus = "active"
	AgentStatusPaused  AgentStatus = "paused"
	AgentStatusRetired AgentStatus = "retired"
)

Defines values for AgentStatus.

func (AgentStatus) Valid added in v0.2.0 

func (e AgentStatus) Valid() bool

Valid indicates whether the value is a known member of the AgentStatus enum.

type AgentsService added in v0.2.0 

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

AgentsService groups the operations on agents. Reach it as client.Agents.

func (*AgentsService) Create added in v0.2.0 

func (s *AgentsService) Create(ctx context.Context, body AgentCreate, opts ...IdempotentRequestOption) (*Agent, error)

Create creates an agent.

Every attempt of the call sends one Idempotency-Key, so a retry cannot create a second agent.

Needs the write scope. Operation createAgent.

func (*AgentsService) Delete added in v0.2.0 

func (s *AgentsService) Delete(ctx context.Context, id string, opts ...RequestOption) error

Delete deletes an agent. It is refused while events reference the agent; set its status to retired instead.

A retry after a lost response can answer 404 for a delete that succeeded.

Needs the write scope. Operation deleteAgent.

func (AgentsService) Format added in v0.2.0 

func (s AgentsService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*AgentsService) Get added in v0.2.0 

func (s *AgentsService) Get(ctx context.Context, id string, query *GetAgentParams, opts ...RequestOption) (*AgentDetail, error)

Get reads an agent, with its statistics. query.From and query.To bound the statistics only; absent bounds, or a nil query, mean all time.

Needs the read scope. Operation getAgent.

func (*AgentsService) List added in v0.2.0 

func (s *AgentsService) List(ctx context.Context, query *ListAgentsParams, opts ...RequestOption) (*Page[AgentListItem, AgentList], error)

List lists agents, and returns the first page. Walk every agent of every page with Page.All. A nil query sends none.

Needs the read scope. Operation listAgents.

func (*AgentsService) Update added in v0.2.0 

func (s *AgentsService) Update(ctx context.Context, id string, patch AgentPatch, opts ...RequestOption) (*Agent, error)

Update updates an agent with a merge patch: a member left out keeps its value, a Null clears it, and any other value sets it.

Never retried.

Needs the write scope. Operation updateAgent.

type AnalyticsService added in v0.2.0 

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

AnalyticsService groups the operations that compute a client's figures. Reach it as client.Analytics.

func (AnalyticsService) Format added in v0.2.0 

func (s AnalyticsService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*AnalyticsService) GetAnomaliesForClient added in v0.2.0 

func (s *AnalyticsService) GetAnomaliesForClient(ctx context.Context, clientID string, query GetClientAnomaliesParams, opts ...RequestOption) (*Anomalies, error)

GetAnomaliesForClient flags anomalies in a client's period, whose bounds are required.

Needs the read scope. Operation getClientAnomalies.

func (*AnalyticsService) GetCostForClient added in v0.2.0 

func (s *AnalyticsService) GetCostForClient(ctx context.Context, clientID string, query GetClientCostParams, opts ...RequestOption) (*ClientCost, error)

GetCostForClient computes a client's cost over a period. Both bounds are required: standing charges are prorated day by day, so an open From would prorate each charge from its own start date, however long ago.

Needs the read scope. Operation getClientCost.

func (*AnalyticsService) GetRoiForClient added in v0.2.0 

func (s *AnalyticsService) GetRoiForClient(ctx context.Context, clientID string, query GetClientRoiParams, opts ...RequestOption) (*RoiResult, error)

GetRoiForClient computes a client's ROI over a period, whose bounds are required.

Needs the read scope. Operation getClientRoi.

func (*AnalyticsService) GetValueForClient added in v0.2.0 

func (s *AnalyticsService) GetValueForClient(ctx context.Context, clientID string, query *GetClientValueParams, opts ...RequestOption) (*ClientValue, error)

GetValueForClient computes a client's value. A nil query, or absent bounds, mean all time.

Needs the read scope. Operation getClientValue.

type Anomalies added in v0.2.0 

type Anomalies struct {
	ClientID string `json:"client_id"`

	// CostSpikes Ascending by date.
	CostSpikes []struct {
		// Baseline The baseline the day is compared with, rounded to `minor_units`. The spike is judged on the unrounded figures, so a rounded `cost` near three times the rounded `baseline` can still be a spike.
		Baseline Decimal `json:"baseline"`

		// Cost The day's cost, rounded to `minor_units`.
		Cost Decimal `json:"cost"`
		Date string  `json:"date"`
	} `json:"cost_spikes"`

	// Currency The currency of `cost_spikes`.
	Currency string `json:"currency"`

	// MinorUnits The scale `cost` and `baseline` in `cost_spikes` are rounded to.
	MinorUnits int `json:"minor_units"`

	// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
	Period Period `json:"period"`

	// UnmappedOutcomeTypes Outcome types no line item prices, by quantity, largest first, then by outcome type compared by Unicode code point. At most 100: `unmapped_outcome_types_omitted` counts the rest.
	UnmappedOutcomeTypes []struct {
		Events      int     `json:"events"`
		OutcomeType string  `json:"outcome_type"`
		Quantity    float64 `json:"quantity"`
	} `json:"unmapped_outcome_types"`

	// UnmappedOutcomeTypesOmitted How many unmapped outcome types `unmapped_outcome_types` leaves out, `0` when it lists every one.
	UnmappedOutcomeTypesOmitted int `json:"unmapped_outcome_types_omitted"`

	// ZeroOutcomeDays Days in the period with no outcome events, ascending.
	ZeroOutcomeDays []string `json:"zero_outcome_days"`
}

Anomalies Pre-validation flags for a period, computed live and stored nowhere.

type AssignedAgent added in v0.2.0 

type AssignedAgent struct {
	AgentKey string `json:"agent_key"`
	ID       string `json:"id"`
	Name     string `json:"name"`

	// Status An agent's lifecycle status.
	Status AgentStatus `json:"status"`
}

AssignedAgent An agent assigned to a client.

type AttributedEvent added in v0.2.0 

type AttributedEvent struct {
	AgentID   string `json:"agent_id"`
	AgentName string `json:"agent_name"`

	// Category An event category.
	Category  EventCategory `json:"category"`
	ClientKey *string       `json:"client_key"`
	Cost      *Decimal      `json:"cost"`
	EventType string        `json:"event_type"`

	// ID The event id: a 64-bit integer as a decimal string, because JavaScript numbers lose precision above 2^53.
	ID          string  `json:"id"`
	Model       *string `json:"model"`
	OutcomeType *string `json:"outcome_type"`
	Quantity    float64 `json:"quantity"`

	// Source How an event arrived: `api` for `POST /v1/events`, `csv` for a CSV import.
	Source    EventSource `json:"source"`
	Timestamp time.Time   `json:"timestamp"`
	TokensIn  *int        `json:"tokens_in"`
	TokensOut *int        `json:"tokens_out"`
}

AttributedEvent One event behind a client's totals.

type Calculation added in v0.2.0 

type Calculation struct {
	// Checklist The validation checklist: the attestation recorded when the calculation was validated. All four checks are `false` until the calculation is validated.
	Checklist  Checklist `json:"checklist"`
	ClientID   string    `json:"client_id"`
	CostTotal  Decimal   `json:"cost_total"`
	CreatedAt  time.Time `json:"created_at"`
	Currency   string    `json:"currency"`
	ID         string    `json:"id"`
	MinorUnits int       `json:"minor_units"`

	// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
	Period      Period     `json:"period"`
	PublishedAt *time.Time `json:"published_at"`

	// Ratios The two return ratios. Both are `null` together, exactly when `undefined_reason` is set.
	Ratios Ratios `json:"ratios"`

	// Snapshot The ROI result frozen when the calculation was created, never rewritten. It is served with the field names it was stored with. A change to its shape increments `snapshot_version`, and this spec describes every version still stored. Version 1 is the `RoiResult` shape. Every list is stored whole. When served, each list the live ROI read limits is put in the same order and limited the same way, and its count of omitted entries is added beside it, so a snapshot and a live read of the same data match. The frozen totals cover every entry.
	Snapshot CalculationSnapshot `json:"snapshot"`

	// State A calculation's position in its lifecycle: `draft` → `validated` → `published`; `validated` → `draft` on reopen. Publication is terminal.
	State       CalculationState `json:"state"`
	ValidatedAt *time.Time       `json:"validated_at"`
	ValueTotal  *Decimal         `json:"value_total"`
}

Calculation A calculation: a client's ROI for one ended period, frozen for validation and publication.

type CalculationCreate added in v0.2.0 

type CalculationCreate struct {
	// Period A half-open range of instants, `[from, to)`. Both sides are required.
	Period PeriodInput `json:"period"`
}

CalculationCreate defines model for CalculationCreate.

type CalculationList added in v0.2.0 

type CalculationList struct {
	// Data One page of items, at most `limit`, in the documented order.
	Data []CalculationSummary `json:"data"`

	// HasMore Whether another page exists.
	HasMore    bool    `json:"has_more"`
	NextCursor *string `json:"next_cursor"`
}

CalculationList A client's calculations: latest period first, then newest first, then id.

type CalculationSnapshot added in v0.2.0 

type CalculationSnapshot struct {
	ClientID string `json:"client_id"`

	// Cost A cost computation.
	Cost       CostResult `json:"cost"`
	Currency   string     `json:"currency"`
	MinorUnits int        `json:"minor_units"`

	// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
	Period Period `json:"period"`

	// Ratios The two return ratios. Both are `null` together, exactly when `undefined_reason` is set.
	Ratios          Ratios `json:"ratios"`
	SnapshotVersion int    `json:"snapshot_version"`

	// Value A value computation.
	Value ValueResult `json:"value"`
}

CalculationSnapshot The ROI result frozen when the calculation was created, never rewritten. It is served with the field names it was stored with. A change to its shape increments `snapshot_version`, and this spec describes every version still stored. Version 1 is the `RoiResult` shape. Every list is stored whole. When served, each list the live ROI read limits is put in the same order and limited the same way, and its count of omitted entries is added beside it, so a snapshot and a live read of the same data match. The frozen totals cover every entry.

type CalculationState added in v0.2.0 

type CalculationState string

CalculationState A calculation's position in its lifecycle: `draft` → `validated` → `published`; `validated` → `draft` on reopen. Publication is terminal. 

const (
	CalculationStateDraft     CalculationState = "draft"
	CalculationStatePublished CalculationState = "published"
	CalculationStateValidated CalculationState = "validated"
)

Defines values for CalculationState.

func (CalculationState) Valid added in v0.2.0 

func (e CalculationState) Valid() bool

Valid indicates whether the value is a known member of the CalculationState enum.

type CalculationSummary added in v0.2.0 

type CalculationSummary struct {
	// Checklist The validation checklist: the attestation recorded when the calculation was validated. All four checks are `false` until the calculation is validated.
	Checklist  Checklist `json:"checklist"`
	ClientID   string    `json:"client_id"`
	CostTotal  Decimal   `json:"cost_total"`
	CreatedAt  time.Time `json:"created_at"`
	Currency   string    `json:"currency"`
	ID         string    `json:"id"`
	IsCurrent  *bool     `json:"is_current"`
	MinorUnits int       `json:"minor_units"`

	// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
	Period      Period     `json:"period"`
	PublishedAt *time.Time `json:"published_at"`

	// Ratios The two return ratios. Both are `null` together, exactly when `undefined_reason` is set.
	Ratios Ratios `json:"ratios"`

	// State A calculation's position in its lifecycle: `draft` → `validated` → `published`; `validated` → `draft` on reopen. Publication is terminal.
	State       CalculationState `json:"state"`
	ValidatedAt *time.Time       `json:"validated_at"`
	ValueTotal  *Decimal         `json:"value_total"`
}

CalculationSummary A calculation as the list returns it: without `snapshot`, with `is_current`.

type CalculationsService added in v0.2.0 

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

CalculationsService groups the operations on calculations, a client's ROI frozen for a period. Reach it as client.Calculations.

func (*CalculationsService) CreateForClient added in v0.2.0 

func (s *CalculationsService) CreateForClient(ctx context.Context, clientID string, body CalculationCreate, opts ...IdempotentRequestOption) (*Calculation, error)

CreateForClient freezes a client's ROI for an ended period as a draft calculation. An API key with the write scope may create a draft; validating and publishing it need a signed-in user, and this SDK does not offer them.

Every attempt of the call sends one Idempotency-Key, so a retry cannot create a second calculation.

Needs the write scope. Operation createCalculation.

func (*CalculationsService) Delete added in v0.2.0 

func (s *CalculationsService) Delete(ctx context.Context, id string, opts ...RequestOption) error

Delete deletes a draft calculation.

A retry after a lost response can answer 404 for a delete that succeeded.

Needs the write scope. Operation deleteCalculation.

func (CalculationsService) Format added in v0.2.0 

func (s CalculationsService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*CalculationsService) Get added in v0.2.0 

func (s *CalculationsService) Get(ctx context.Context, id string, opts ...RequestOption) (*Calculation, error)

Get reads a calculation.

Needs the read scope. Operation getCalculation.

func (*CalculationsService) ListForClient added in v0.2.0 

func (s *CalculationsService) ListForClient(ctx context.Context, clientID string, query *ListClientCalculationsParams, opts ...RequestOption) (*Page[CalculationSummary, CalculationList], error)

ListForClient lists a client's calculations, and returns the first page. Walk every calculation of every page with Page.All. A nil query sends none.

Needs the read scope. Operation listClientCalculations.

type Checklist added in v0.2.0 

type Checklist struct {
	CostsReviewed     bool `json:"costs_reviewed"`
	CountsSpotChecked bool `json:"counts_spot_checked"`
	CoverageConfirmed bool `json:"coverage_confirmed"`

	// Note Free text, `""` when empty.
	Note              string `json:"note"`
	UnitValuesCurrent bool   `json:"unit_values_current"`
}

Checklist The validation checklist: the attestation recorded when the calculation was validated. All four checks are `false` until the calculation is validated.

type Client 

type Client struct {
	// Events groups the operations on events: ingest, and the events
	// behind a client's totals.
	Events *EventsService
	// Imports groups the CSV import operations.
	Imports *ImportsService
	// Clients groups the operations on clients.
	Clients *ClientsService
	// Agents groups the operations on agents.
	Agents *AgentsService
	// ValueModels groups the operations on value models and value
	// templates.
	ValueModels *ValueModelsService
	// OutcomeTypes groups the operations on outcome types.
	OutcomeTypes *OutcomeTypesService
	// Cost groups the operations on cost line items and the price table.
	Cost *CostService
	// Analytics groups the operations that compute a client's figures.
	Analytics *AnalyticsService
	// Calculations groups the operations on calculations.
	Calculations *CalculationsService
	// Reports groups the operations on reports.
	Reports *ReportsService
	// Dashboard groups the operations on the workspace's dashboard.
	Dashboard *DashboardService
	// Health groups the liveness check.
	Health *HealthService
	// contains filtered or unexported fields
}

Client calls the allisall API. Build one with NewClient and reuse it; it is safe for concurrent use and holds nothing that needs closing.

func NewClient 

func NewClient(opts ...Option) (*Client, error)

NewClient builds a Client. It resolves the credential and the base URL once, here, and fails rather than waiting for a request to fail.

The credential is the WithAPIKey key or the WithTokenProvider provider; passing both is an error. Without either, it is AIA_API_KEY from the environment, when set and not empty. Without that, NewClient fails.

Every error NewClient returns matches errors.Is(err, ErrAllisall).

func (Client) Format 

func (c Client) Format(f fmt.State, _ rune)

Format prints the client for the fmt verbs %v, %+v, %#v and %s, without its credential: only whether it holds an API key or a token provider, and its base URL.

type ClientAgents added in v0.2.0 

type ClientAgents struct {
	// Agents The stored set, ordered by name, case-insensitively.
	Agents []AssignedAgent `json:"agents"`
}

ClientAgents defines model for ClientAgents.

type ClientAgentsSet added in v0.2.0 

type ClientAgentsSet struct {
	// AgentIds The complete set of assigned agents, at most 200. `[]` clears it. An id naming no agent in the workspace is refused with `unknown_reference`. A longer array is refused at its 201st element with one `too_many` at `/agent_ids`.
	AgentIds []string `json:"agent_ids"`
}

ClientAgentsSet defines model for ClientAgentsSet.

type ClientCost added in v0.2.0 

type ClientCost struct {
	// AgentLines Cost per agent, by `total`, largest first, then by `agent_id`. At most 100: `agent_lines_omitted` counts the rest.
	AgentLines []AgentCostLine `json:"agent_lines"`

	// AgentLinesOmitted How many agents `agent_lines` leaves out, `0` when it lists every one.
	AgentLinesOmitted int    `json:"agent_lines_omitted"`
	ClientID          string `json:"client_id"`

	// Coverage Every way cost could be missing from the total.
	Coverage CostCoverage `json:"coverage"`
	Currency string       `json:"currency"`

	// Manual Cost line items, prorated. The sum covers every line item, listed or not.
	Manual Decimal `json:"manual"`

	// ManualLines The cost line items reaching the client in the period, by `total`, largest first, then by `id`. At most 100: `manual_lines_omitted` counts the rest.
	ManualLines []ManualCostLine `json:"manual_lines"`

	// ManualLinesOmitted How many line items `manual_lines` leaves out, `0` when it lists every one.
	ManualLinesOmitted int `json:"manual_lines_omitted"`
	MinorUnits         int `json:"minor_units"`

	// PassThrough The sum of event `cost`.
	PassThrough Decimal `json:"pass_through"`

	// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
	Period Period `json:"period"`

	// TokenLines One line for each model the price table prices, so at most 200, as the price table holds at most 200 models. By `total`, largest first, then by model compared by Unicode code point.
	TokenLines []TokenCostLine `json:"token_lines"`

	// TokenValued Uncosted model events valued at the price table.
	TokenValued Decimal `json:"token_valued"`
	Total       Decimal `json:"total"`
}

ClientCost A client's operating cost over a period.

type ClientCreate added in v0.2.0 

type ClientCreate struct {
	ClientKey *string `json:"client_key,omitempty"`

	// Name Free text, trimmed of white space (the Unicode `White_Space` property) at both ends. The trimmed name is stored. It holds 1 to 200 characters, counted in Unicode code points after trimming: blank after trimming is `required`, and longer than 200 characters after trimming is `too_long`. U+0000 is `invalid_format`, as in every request string. No JSON Schema keyword measures a length after trimming, so the schema states no `maxLength`; a `maxLength` of 200 would refuse a padded name the server accepts.
	Name        string  `json:"name"`
	Notes       *string `json:"notes,omitempty"`
	RenewalDate *string `json:"renewal_date,omitempty"`

	// Status A client's lifecycle status.
	Status ClientStatus `json:"status"`
}

ClientCreate defines model for ClientCreate.

type ClientDetail added in v0.2.0 

type ClientDetail struct {
	// Agents The assigned agents, ordered by name, case-insensitively.
	Agents             []AssignedAgent `json:"agents"`
	ClientKey          *string         `json:"client_key"`
	CreatedAt          time.Time       `json:"created_at"`
	EarliestActivityAt *time.Time      `json:"earliest_activity_at"`
	ID                 string          `json:"id"`

	// Name Free text, at most 200 characters.
	Name string `json:"name"`

	// Notes Free text, `""` when empty.
	Notes       string  `json:"notes"`
	RenewalDate *string `json:"renewal_date"`

	// Status A client's lifecycle status.
	Status ClientStatus `json:"status"`
}

ClientDetail A client with its assigned agents, as the single read returns it.

type ClientEventList added in v0.2.0 

type ClientEventList struct {
	ClientID string `json:"client_id"`

	// Currency The currency of every `cost` in `data`, given once here. An event's stored `currency` is not exposed: it is always `null` or the workspace currency, because a mismatching event is refused.
	Currency string `json:"currency"`

	// Data At most `limit`, in the requested order; ties break on the event id, descending.
	Data       []AttributedEvent `json:"data"`
	HasMore    bool              `json:"has_more"`
	NextCursor *string           `json:"next_cursor"`
	Page       *int              `json:"page"`

	// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
	Period Period `json:"period"`

	// Total Every event matching the filters, not only this page.
	Total int `json:"total"`
}

ClientEventList The events behind a client's totals. The shared list envelope plus this list's own members. It is the one list that also takes `page` and returns `total`; `page` and the cursor are one offset with two spellings.

type ClientList added in v0.2.0 

type ClientList struct {
	// Data One page of items, at most `limit`, in the documented order.
	Data []ClientRecord `json:"data"`

	// HasMore Whether another page exists.
	HasMore    bool    `json:"has_more"`
	NextCursor *string `json:"next_cursor"`
}

ClientList Clients, ordered by name case-insensitively, then id.

type ClientPatch added in v0.2.0 

type ClientPatch struct {
	ClientKey Nullable[string] `json:"client_key,omitzero"`

	// Name Free text, trimmed of white space (the Unicode `White_Space` property) at both ends. The trimmed name is stored. It holds 1 to 200 characters, counted in Unicode code points after trimming: blank after trimming is `required`, and longer than 200 characters after trimming is `too_long`. U+0000 is `invalid_format`, as in every request string. No JSON Schema keyword measures a length after trimming, so the schema states no `maxLength`; a `maxLength` of 200 would refuse a padded name the server accepts.
	Name        *string          `json:"name,omitempty"`
	Notes       Nullable[string] `json:"notes,omitzero"`
	RenewalDate Nullable[string] `json:"renewal_date,omitzero"`

	// Status A client's lifecycle status.
	Status *ClientStatus `json:"status,omitempty"`
}

ClientPatch A JSON Merge Patch (RFC 7396): an absent member is unchanged, `null` clears a member. The merged client is validated whole.

type ClientRecord added in v0.2.0 

type ClientRecord struct {
	ClientKey *string   `json:"client_key"`
	CreatedAt time.Time `json:"created_at"`
	ID        string    `json:"id"`

	// Name Free text, at most 200 characters.
	Name string `json:"name"`

	// Notes Free text, `""` when empty.
	Notes       string  `json:"notes"`
	RenewalDate *string `json:"renewal_date"`

	// Status A client's lifecycle status.
	Status ClientStatus `json:"status"`
}

ClientRecord A client: the roster record value is delivered to.

In the API reference, this schema is named Client.

type ClientStatus added in v0.2.0 

type ClientStatus string

ClientStatus A client's lifecycle status. 

const (
	ClientStatusActive   ClientStatus = "active"
	ClientStatusChurned  ClientStatus = "churned"
	ClientStatusProspect ClientStatus = "prospect"
)

Defines values for ClientStatus.

func (ClientStatus) Valid added in v0.2.0 

func (e ClientStatus) Valid() bool

Valid indicates whether the value is a known member of the ClientStatus enum.

type ClientValue added in v0.2.0 

type ClientValue struct {
	ClientID string `json:"client_id"`

	// Coverage Every way value could be missing from the total.
	Coverage ValueCoverage `json:"coverage"`
	Currency string        `json:"currency"`

	// Lines One line for each line item of the model, in line-item order, so at most 50. An outcome type no line item prices is never a line; it is listed in `coverage.unpriced_outcome_types`.
	Lines      []ValueLine `json:"lines"`
	MinorUnits int         `json:"minor_units"`

	// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
	Period     Period         `json:"period"`
	Total      *Decimal       `json:"total"`
	ValueModel *ValueModelRef `json:"value_model"`
}

ClientValue A client's value over a period.

type ClientsService added in v0.2.0 

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

ClientsService groups the operations on clients, the partner's own customers. Reach it as client.Clients.

func (*ClientsService) Create added in v0.2.0 

func (s *ClientsService) Create(ctx context.Context, body ClientCreate, opts ...IdempotentRequestOption) (*ClientRecord, error)

Create creates a client.

Every attempt of the call sends one Idempotency-Key, so a retry cannot create a second client.

Needs the write scope. Operation createClient.

func (*ClientsService) Delete added in v0.2.0 

func (s *ClientsService) Delete(ctx context.Context, id string, opts ...RequestOption) error

Delete deletes a client. It is refused while events carry the client's key, or while the client has a validated or published calculation; set its status to churned instead.

A retry after a lost response can answer 404 for a delete that succeeded.

Needs the write scope. Operation deleteClient.

func (ClientsService) Format added in v0.2.0 

func (s ClientsService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*ClientsService) Get added in v0.2.0 

func (s *ClientsService) Get(ctx context.Context, id string, opts ...RequestOption) (*ClientDetail, error)

Get reads a client.

Needs the read scope. Operation getClient.

func (*ClientsService) List added in v0.2.0 

func (s *ClientsService) List(ctx context.Context, query *ListClientsParams, opts ...RequestOption) (*Page[ClientRecord, ClientList], error)

List lists clients, and returns the first page. Walk every client of every page with Page.All. A nil query sends none.

Needs the read scope. Operation listClients.

func (*ClientsService) SetAgents added in v0.2.0 

func (s *ClientsService) SetAgents(ctx context.Context, id string, body ClientAgentsSet, opts ...RequestOption) (*ClientAgents, error)

SetAgents replaces a client's assigned agents. Assignment decides how later events are attributed: an event without client_key from an agent assigned to exactly one client is attributed to that client. A model or outcome event from an agent assigned to two or more clients must carry client_key, or it is refused with client_key_required.

Retried, because a repeat leaves the same assignment.

Needs the write scope. Operation setClientAgents.

func (*ClientsService) Update added in v0.2.0 

func (s *ClientsService) Update(ctx context.Context, id string, patch ClientPatch, opts ...RequestOption) (*ClientRecord, error)

Update updates a client with a merge patch: a member left out keeps its value, a Null clears it, and any other value sets it.

Never retried.

Needs the write scope. Operation updateClient.

type ConnectionError 

type ConnectionError struct {
	// RequestID is the X-Request-Id the SDK sent on the last attempt, to
	// quote even though no response arrived.
	RequestID string
	// Err is the underlying cause.
	Err error
}

ConnectionError is a request that got no response: the connection failed or was reset, or the attempt timed out.

func (*ConnectionError) Error 

func (e *ConnectionError) Error() string

Error describes the error.

func (*ConnectionError) Is 

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

Is reports whether target is ErrAllisall.

func (*ConnectionError) Unwrap 

func (e *ConnectionError) Unwrap() error

Unwrap returns the underlying cause.

type CostCoverage added in v0.2.0 

type CostCoverage struct {
	// PartiallyCoveredLineItems Line items covering only part of the period, by `total`, largest first, then by `id`. At most 100: `partially_covered_line_items_omitted` counts the rest.
	PartiallyCoveredLineItems []ManualCostLine `json:"partially_covered_line_items"`

	// PartiallyCoveredLineItemsOmitted How many partly covering line items `partially_covered_line_items` leaves out, `0` when it lists every one.
	PartiallyCoveredLineItemsOmitted int `json:"partially_covered_line_items_omitted"`

	// PeriodTruncated Whether proration stopped before the end of the period because the period has not ended.
	PeriodTruncated bool   `json:"period_truncated"`
	ProratedThrough string `json:"prorated_through"`

	// TokenValuedEvents Uncosted model events valued from their tokens.
	TokenValuedEvents int `json:"token_valued_events"`

	// UnattributedLineItems By label compared by Unicode code point, then by `id`. At most 100: `unattributed_line_items_omitted` counts the rest.
	UnattributedLineItems []UnattributedLineItem `json:"unattributed_line_items"`

	// UnattributedLineItemsOmitted How many unattributed line items `unattributed_line_items` leaves out, `0` when it lists every one.
	UnattributedLineItemsOmitted int `json:"unattributed_line_items_omitted"`

	// UncostedModelEvents Model events with no `cost`.
	UncostedModelEvents int `json:"uncosted_model_events"`

	// UnpriceableModels Models on uncosted events that the price table does not price, by event count, largest first, then by model compared by Unicode code point. At most 100: `unpriceable_models_omitted` counts the rest.
	UnpriceableModels []struct {
		Events int    `json:"events"`
		Model  string `json:"model"`
	} `json:"unpriceable_models"`

	// UnpriceableModelsOmitted How many unpriceable models `unpriceable_models` leaves out, `0` when it lists every one. `uncosted_model_events` counts the events of every one.
	UnpriceableModelsOmitted int `json:"unpriceable_models_omitted"`
}

CostCoverage Every way cost could be missing from the total.

type CostLineItem added in v0.2.0 

type CostLineItem struct {
	CreatedAt time.Time `json:"created_at"`
	Currency  string    `json:"currency"`
	EndDate   *string   `json:"end_date"`
	ID        string    `json:"id"`

	// Label Free text.
	Label         string  `json:"label"`
	MonthlyAmount Decimal `json:"monthly_amount"`
	StartDate     string  `json:"start_date"`

	// Target What a cost line item is charged to: a client or an agent.
	Target    CostTarget `json:"target"`
	UpdatedAt time.Time  `json:"updated_at"`
}

CostLineItem A standing monthly charge the event stream never sees. Its dates include both ends.

type CostLineItemCreate added in v0.2.0 

type CostLineItemCreate struct {
	EndDate *string `json:"end_date,omitempty"`

	// Label Free text, trimmed of white space (the Unicode `White_Space` property) at both ends. The trimmed label is stored. It holds 1 to 200 characters, counted in Unicode code points after trimming: blank after trimming is `required`, and longer than 200 characters after trimming is `too_long`. U+0000 is `invalid_format`, as in every request string. No JSON Schema keyword measures a length after trimming, so the schema states no `maxLength`; a `maxLength` of 200 would refuse a padded label the server accepts.
	Label string `json:"label"`

	// MonthlyAmount In the workspace currency. At least 0 and below 100,000,000, with at most 4 decimal places; more is refused with `too_precise`. Required: absent or `null` is refused with `required`, and `0` must be sent explicitly.
	MonthlyAmount Decimal `json:"monthly_amount"`
	StartDate     string  `json:"start_date"`

	// Target The writable part of `target`. `name` is read-only.
	Target CostTargetInput `json:"target"`
}

CostLineItemCreate defines model for CostLineItemCreate.

type CostLineItemList added in v0.2.0 

type CostLineItemList struct {
	// Data One page of items, at most `limit`, in the documented order.
	Data []CostLineItem `json:"data"`

	// HasMore Whether another page exists.
	HasMore    bool    `json:"has_more"`
	NextCursor *string `json:"next_cursor"`
}

CostLineItemList Line items, newest first, then id.

type CostLineItemPatch added in v0.2.0 

type CostLineItemPatch struct {
	EndDate Nullable[string] `json:"end_date,omitzero"`

	// Label Free text, trimmed of white space (the Unicode `White_Space` property) at both ends. The trimmed label is stored. It holds 1 to 200 characters, counted in Unicode code points after trimming: blank after trimming is `required`, and longer than 200 characters after trimming is `too_long`. U+0000 is `invalid_format`, as in every request string. No JSON Schema keyword measures a length after trimming, so the schema states no `maxLength`; a `maxLength` of 200 would refuse a padded label the server accepts.
	Label *string `json:"label,omitempty"`

	// MonthlyAmount In the workspace currency. At least 0 and below 100,000,000, with at most 4 decimal places; more is refused with `too_precise`.
	MonthlyAmount *Decimal `json:"monthly_amount,omitempty"`
	StartDate     *string  `json:"start_date,omitempty"`

	// Target The writable part of `target`. `name` is read-only.
	Target *CostTargetInput `json:"target,omitempty"`
}

CostLineItemPatch A JSON Merge Patch (RFC 7396). The merged line item is validated whole.

type CostResult added in v0.2.0 

type CostResult struct {
	// AgentLines Cost per agent, by `total`, largest first, then by `agent_id`. At most 100: `agent_lines_omitted` counts the rest.
	AgentLines []AgentCostLine `json:"agent_lines"`

	// AgentLinesOmitted How many agents `agent_lines` leaves out, `0` when it lists every one.
	AgentLinesOmitted int `json:"agent_lines_omitted"`

	// Coverage Every way cost could be missing from the total.
	Coverage CostCoverage `json:"coverage"`

	// Manual Cost line items, prorated. The sum covers every line item, listed or not.
	Manual Decimal `json:"manual"`

	// ManualLines The cost line items reaching the client in the period, by `total`, largest first, then by `id`. At most 100: `manual_lines_omitted` counts the rest.
	ManualLines []ManualCostLine `json:"manual_lines"`

	// ManualLinesOmitted How many line items `manual_lines` leaves out, `0` when it lists every one.
	ManualLinesOmitted int `json:"manual_lines_omitted"`

	// PassThrough The sum of event `cost`.
	PassThrough Decimal `json:"pass_through"`

	// TokenLines One line for each model the price table prices, so at most 200, as the price table holds at most 200 models. By `total`, largest first, then by model compared by Unicode code point.
	TokenLines []TokenCostLine `json:"token_lines"`

	// TokenValued Uncosted model events valued at the price table.
	TokenValued Decimal `json:"token_valued"`
	Total       Decimal `json:"total"`
}

CostResult A cost computation.

type CostService added in v0.2.0 

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

CostService groups the operations on cost line items and the price table. Reach it as client.Cost.

func (*CostService) CreateLineItem added in v0.2.0 

func (s *CostService) CreateLineItem(ctx context.Context, body CostLineItemCreate, opts ...IdempotentRequestOption) (*CostLineItem, error)

CreateLineItem creates a cost line item.

Every attempt of the call sends one Idempotency-Key, so a retry cannot create a second line item.

Needs the write scope. Operation createCostLineItem.

func (*CostService) DeleteLineItem added in v0.2.0 

func (s *CostService) DeleteLineItem(ctx context.Context, id string, opts ...RequestOption) error

DeleteLineItem deletes a cost line item.

A retry after a lost response can answer 404 for a delete that succeeded.

Needs the write scope. Operation deleteCostLineItem.

func (CostService) Format added in v0.2.0 

func (s CostService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*CostService) GetLineItem added in v0.2.0 

func (s *CostService) GetLineItem(ctx context.Context, id string, opts ...RequestOption) (*CostLineItem, error)

GetLineItem reads a cost line item.

Needs the read scope. Operation getCostLineItem.

func (*CostService) GetPriceTable added in v0.2.0 

func (s *CostService) GetPriceTable(ctx context.Context, opts ...RequestOption) (*PriceTable, error)

GetPriceTable reads the price table.

Needs the read scope. Operation getPriceTable.

func (*CostService) ListLineItems added in v0.2.0 

func (s *CostService) ListLineItems(ctx context.Context, query *ListCostLineItemsParams, opts ...RequestOption) (*Page[CostLineItem, CostLineItemList], error)

ListLineItems lists cost line items, and returns the first page. Walk every line item of every page with Page.All. A nil query sends none.

Needs the read scope. Operation listCostLineItems.

func (*CostService) SetPriceTable added in v0.2.0 

func (s *CostService) SetPriceTable(ctx context.Context, body PriceTableSet, opts ...RequestOption) (*PriceTable, error)

SetPriceTable replaces the price table, as a whole. Each rate is a Decimal, so the rates of a table read with CostService.GetPriceTable are sent back with the same digits.

Retried, because a repeat leaves the same price table.

Needs the write scope. Operation setPriceTable.

func (*CostService) UpdateLineItem added in v0.2.0 

func (s *CostService) UpdateLineItem(ctx context.Context, id string, patch CostLineItemPatch, opts ...RequestOption) (*CostLineItem, error)

UpdateLineItem updates a cost line item with a merge patch: a member left out keeps its value, a Null clears it, and any other value sets it.

Never retried.

Needs the write scope. Operation updateCostLineItem.

type CostTarget added in v0.2.0 

type CostTarget struct {
	ID string `json:"id"`

	// Kind What a cost line item is charged to.
	Kind CostTargetKind `json:"kind"`

	// Name The target's display name.
	Name string `json:"name"`
}

CostTarget What a cost line item is charged to: a client or an agent.

type CostTargetInput added in v0.2.0 

type CostTargetInput struct {
	// ID An id naming no client or agent in the workspace is refused with `unknown_reference`.
	ID string `json:"id"`

	// Kind What a cost line item is charged to.
	Kind CostTargetKind `json:"kind"`
}

CostTargetInput The writable part of `target`. `name` is read-only.

type CostTargetKind added in v0.2.0 

type CostTargetKind string

CostTargetKind What a cost line item is charged to. 

const (
	CostTargetKindAgent  CostTargetKind = "agent"
	CostTargetKindClient CostTargetKind = "client"
)

Defines values for CostTargetKind.

func (CostTargetKind) Valid added in v0.2.0 

func (e CostTargetKind) Valid() bool

Valid indicates whether the value is a known member of the CostTargetKind enum.

type Dashboard added in v0.2.0 

type Dashboard struct {
	// AgentCosts The five agents with the highest cost, by `total`, largest first, then by `agent_id`.
	AgentCosts []AgentCostLine `json:"agent_costs"`

	// AgentCostsRecorded Agents with recorded cost in the month.
	AgentCostsRecorded int `json:"agent_costs_recorded"`

	// Clients In the requested sort order; clients with no value for the sort key last, then by name, then by id. At most 1,000: `clients_omitted` counts the rest.
	Clients []PortfolioClient `json:"clients"`

	// ClientsOmitted How many clients `clients` leaves out, `0` when it lists every one. `counted` and the totals cover every client.
	ClientsOmitted int `json:"clients_omitted"`
	CostComponents struct {
		Manual      Decimal `json:"manual"`
		PassThrough Decimal `json:"pass_through"`
		TokenValued Decimal `json:"token_valued"`
	} `json:"cost_components"`
	CostTotal Decimal `json:"cost_total"`

	// Counted Clients counted in the totals.
	Counted              int     `json:"counted"`
	Currency             string  `json:"currency"`
	LatestPublishedMonth *string `json:"latest_published_month"`
	MinorUnits           int     `json:"minor_units"`
	Onboarding           struct {
		HasAssignedAgent  bool `json:"has_assigned_agent"`
		HasClient         bool `json:"has_client"`
		HasEvents         bool `json:"has_events"`
		HasPricedOutcomes bool `json:"has_priced_outcomes"`
		HasPublished      bool `json:"has_published"`
	} `json:"onboarding"`

	// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
	Period Period `json:"period"`

	// PeriodEnded Whether the month has ended.
	PeriodEnded bool `json:"period_ended"`

	// Ratios The two return ratios. Both are `null` together, exactly when `undefined_reason` is set.
	Ratios Ratios `json:"ratios"`

	// TopClients The five counted clients with the highest `value_total`, largest first, then by `client_id`, chosen from every client whether or not `clients` lists it, and whatever `sort` and `dir` say. Fewer than five when fewer are counted. Each entry has the shape of a `clients` entry, with a `value_total` and a `reason` of `null`.
	TopClients []PortfolioClient `json:"top_clients"`

	// UnallocatedCharges Charges on agents serving several clients or none, which reach no client, by `total`, largest first, then by label compared by Unicode code point, then by `id`. At most 100: `unallocated_charges_omitted` counts the rest.
	UnallocatedCharges []struct {
		AgentID   string  `json:"agent_id"`
		AgentName string  `json:"agent_name"`
		ID        string  `json:"id"`
		Label     string  `json:"label"`
		Total     Decimal `json:"total"`
	} `json:"unallocated_charges"`

	// UnallocatedChargesOmitted How many charges `unallocated_charges` leaves out, `0` when it lists every one.
	UnallocatedChargesOmitted int `json:"unallocated_charges_omitted"`

	// UnpricedOutcomeTypes Unpriced outcome types across the counted clients' figures, by event count, largest first, then by outcome type compared by Unicode code point. An outcome type is grouped ignoring case and surrounding spaces, with its events summed across spellings. At most 100: `unpriced_outcome_types_omitted` counts the rest.
	UnpricedOutcomeTypes []struct {
		Events      int    `json:"events"`
		OutcomeType string `json:"outcome_type"`
	} `json:"unpriced_outcome_types"`

	// UnpricedOutcomeTypesOmitted How many unpriced outcome types `unpriced_outcome_types` leaves out, `0` when it lists every one.
	UnpricedOutcomeTypesOmitted int `json:"unpriced_outcome_types_omitted"`

	// ValueByOutcome Value by priced outcome type across the counted clients, by `total`, largest first, then by outcome type compared by Unicode code point. An outcome type is grouped ignoring case and surrounding spaces, with its value and events summed across spellings. At most 100: `value_by_outcome_omitted` counts the rest.
	ValueByOutcome []struct {
		Events      int     `json:"events"`
		Label       string  `json:"label"`
		OutcomeType string  `json:"outcome_type"`
		Total       Decimal `json:"total"`
	} `json:"value_by_outcome"`

	// ValueByOutcomeOmitted How many outcome types `value_by_outcome` leaves out, `0` when it lists every one. `value_total` covers every one.
	ValueByOutcomeOmitted int `json:"value_by_outcome_omitted"`

	// ValueByOutcomeOmittedTotal The value of the outcome types `value_by_outcome` leaves out, `0` when it lists every one. The `total` of every listed entry plus this equals `value_total` exactly, as decimals, for figures of up to 15 significant digits, so a chart can show the rest as one share without adding money itself.
	ValueByOutcomeOmittedTotal Decimal `json:"value_by_outcome_omitted_total"`

	// ValueTotal The sum of the counted clients' value totals, added as decimals. It equals the `total` of every `value_by_outcome` entry plus `value_by_outcome_omitted_total`, for figures of up to 15 significant digits.
	ValueTotal Decimal `json:"value_total"`
}

Dashboard The workspace's published figures for one month. `GET /v1/dashboard`, which returns it, and `GET /v1/dashboard/renewals` are expected to change shape before `/v1` is declared stable.

type DashboardService added in v0.2.0 

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

DashboardService groups the operations on the workspace's dashboard. Reach it as client.Dashboard.

func (DashboardService) Format added in v0.2.0 

func (s DashboardService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*DashboardService) Get added in v0.2.0 

func (s *DashboardService) Get(ctx context.Context, query GetDashboardParams, opts ...RequestOption) (*Dashboard, error)

Get reads the workspace's month: its published figures for the calendar month query.Month, such as "2026-08", which is required.

Needs the read scope. Operation getDashboard.

func (*DashboardService) ListRenewals added in v0.2.0 

func (s *DashboardService) ListRenewals(ctx context.Context, query *ListRenewalsParams, opts ...RequestOption) (*Page[Renewal, RenewalList], error)

ListRenewals lists renewal readiness: each client's latest published figures, whatever month DashboardService.Get reads. It returns the first page; walk every client of every page with Page.All. A nil query sends none.

Needs the read scope. Operation listRenewals.

type Decimal 

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

Decimal is an exact decimal number, used for money. It holds the number's text and writes it to JSON verbatim, and reads a JSON number from its text, so money never passes through a binary float on its way to or from the API.

Build one with ParseDecimal, MustParseDecimal or DecimalFromFloat. The zero Decimal is 0.

func DecimalFromFloat 

func DecimalFromFloat(f float64) (Decimal, error)

DecimalFromFloat returns the Decimal written by the shortest plain decimal text that reads back as f. For any value of up to 15 significant digits, that is the literal the caller wrote: 0.3683 gives "0.3683". It refuses NaN and the infinities.

func MustParseDecimal 

func MustParseDecimal(s string) Decimal

MustParseDecimal is like ParseDecimal but panics if s is not a decimal number. It is meant for constants in source code, such as MustParseDecimal("0.25").

func ParseDecimal 

func ParseDecimal(s string) (Decimal, error)

ParseDecimal returns the Decimal written by s: an optional "-", then either "0" or digits without a leading zero, then optionally "." and one or more digits. "12.50", "-0.3683" and "100" are accepted; "1e2", "+1", "01", ".5" and "1." are not.

The API refuses a cost with more than 6 decimal places, as a row error. ParseDecimal does not check that, so the rule lives in one place.

func (Decimal) MarshalJSON 

func (d Decimal) MarshalJSON() ([]byte, error)

MarshalJSON writes the Decimal's text as a JSON number, verbatim.

func (Decimal) String 

func (d Decimal) String() string

String returns the Decimal's text.

func (*Decimal) UnmarshalJSON added in v0.2.0 

func (d *Decimal) UnmarshalJSON(data []byte) error

UnmarshalJSON reads a JSON number from its text, before any binary float exists, so the Decimal holds exactly the digits the API sent. A number in exponent form is written out in plain digits by moving the decimal point, which never rounds: 1e-7 becomes 0.0000001 and 1.5E+3 becomes 1500. An exponent whose magnitude is over 400 is refused.

Any JSON value other than a number, a string included, is refused. A JSON null leaves the Decimal unchanged.

type Disclosure added in v0.2.0 

type Disclosure struct {
	// Facts The facts a caller needs to write the sentence for this finding. Its members depend on `kind`, as `DisclosureKind` lists.
	Facts map[string]interface{} `json:"facts"`

	// Included Whether the finding goes out on the shared report.
	Included bool `json:"included"`

	// Kind A coverage finding on a report. Each kind appears at most once per report. `facts` per kind: `empty` `{}`; `unpriced` `{outcome_types: [{outcome_type, quantity}], outcome_types_omitted}`, at most 100 outcome types by quantity, largest first, with `outcome_types_omitted` counting the rest, which a report composed before the count existed lacks; `key_unset` `{}`; `unmatched` `{keys}`; `unattributable` `{events}`; `precedes` `{}`; `unpriceable` `{models}`; `uncosted` `{events}`; `token_valued` `{events}`; `unattributed` `{line_items}`; `partial` `{line_items}`; `truncated` `{prorated_through}`.
	Kind DisclosureKind `json:"kind"`
	Text *string        `json:"text"`
}

Disclosure One coverage finding as it appears on a report.

type DisclosureEdit added in v0.2.0 

type DisclosureEdit struct {
	Included bool `json:"included"`

	// Kind A coverage finding on a report. Each kind appears at most once per report. `facts` per kind: `empty` `{}`; `unpriced` `{outcome_types: [{outcome_type, quantity}], outcome_types_omitted}`, at most 100 outcome types by quantity, largest first, with `outcome_types_omitted` counting the rest, which a report composed before the count existed lacks; `key_unset` `{}`; `unmatched` `{keys}`; `unattributable` `{events}`; `precedes` `{}`; `unpriceable` `{models}`; `uncosted` `{events}`; `token_valued` `{events}`; `unattributed` `{line_items}`; `partial` `{line_items}`; `truncated` `{prorated_through}`.
	Kind DisclosureKind `json:"kind"`
	Text *string        `json:"text,omitempty"`
}

DisclosureEdit defines model for DisclosureEdit.

type DisclosureKind added in v0.2.0 

type DisclosureKind string

DisclosureKind A coverage finding on a report. Each kind appears at most once per report. `facts` per kind: `empty` `{}`; `unpriced` `{outcome_types: [{outcome_type, quantity}], outcome_types_omitted}`, at most 100 outcome types by quantity, largest first, with `outcome_types_omitted` counting the rest, which a report composed before the count existed lacks; `key_unset` `{}`; `unmatched` `{keys}`; `unattributable` `{events}`; `precedes` `{}`; `unpriceable` `{models}`; `uncosted` `{events}`; `token_valued` `{events}`; `unattributed` `{line_items}`; `partial` `{line_items}`; `truncated` `{prorated_through}`. 

const (
	DisclosureKindEmpty          DisclosureKind = "empty"
	DisclosureKindKeyUnset       DisclosureKind = "key_unset"
	DisclosureKindPartial        DisclosureKind = "partial"
	DisclosureKindPrecedes       DisclosureKind = "precedes"
	DisclosureKindTokenValued    DisclosureKind = "token_valued"
	DisclosureKindTruncated      DisclosureKind = "truncated"
	DisclosureKindUnattributable DisclosureKind = "unattributable"
	DisclosureKindUnattributed   DisclosureKind = "unattributed"
	DisclosureKindUncosted       DisclosureKind = "uncosted"
	DisclosureKindUnmatched      DisclosureKind = "unmatched"
	DisclosureKindUnpriceable    DisclosureKind = "unpriceable"
	DisclosureKindUnpriced       DisclosureKind = "unpriced"
)

Defines values for DisclosureKind.

func (DisclosureKind) Valid added in v0.2.0 

func (e DisclosureKind) Valid() bool

Valid indicates whether the value is a known member of the DisclosureKind enum.

type ErrorCode 

type ErrorCode string

ErrorCode is the code of an error response. The set is open: the API may send a code this SDK does not list, and it is kept as it arrived. 

const (
	ErrorCodeInvalidJSON                  ErrorCode = "invalid_json"
	ErrorCodeValidationFailed             ErrorCode = "validation_failed"
	ErrorCodeUnauthenticated              ErrorCode = "unauthenticated"
	ErrorCodeInsufficientScope            ErrorCode = "insufficient_scope"
	ErrorCodeSessionRequired              ErrorCode = "session_required"
	ErrorCodeAccountNotProvisioned        ErrorCode = "account_not_provisioned"
	ErrorCodeNotFound                     ErrorCode = "not_found"
	ErrorCodeNoActiveValueModel           ErrorCode = "no_active_value_model"
	ErrorCodeMethodNotAllowed             ErrorCode = "method_not_allowed"
	ErrorCodeIdempotencyKeyInUse          ErrorCode = "idempotency_key_in_use"
	ErrorCodeClientKeyInUse               ErrorCode = "client_key_in_use"
	ErrorCodeAgentKeyInUse                ErrorCode = "agent_key_in_use"
	ErrorCodeClientHasEvents              ErrorCode = "client_has_events"
	ErrorCodeClientHasCalculations        ErrorCode = "client_has_calculations"
	ErrorCodeAgentHasEvents               ErrorCode = "agent_has_events"
	ErrorCodeClientKeyHasEvents           ErrorCode = "client_key_has_events"
	ErrorCodeValueModelExists             ErrorCode = "value_model_exists"
	ErrorCodeValueModelVersionStale       ErrorCode = "value_model_version_stale"
	ErrorCodeCalculationTransitionInvalid ErrorCode = "calculation_transition_invalid"
	ErrorCodeCalculationNotDraft          ErrorCode = "calculation_not_draft"
	ErrorCodeCalculationNotPublished      ErrorCode = "calculation_not_published"
	ErrorCodeReportShared                 ErrorCode = "report_shared"
	ErrorCodeReportNotShared              ErrorCode = "report_not_shared"
	ErrorCodeAPIKeyRevoked                ErrorCode = "api_key_revoked"
	ErrorCodePayloadTooLarge              ErrorCode = "payload_too_large"
	ErrorCodeURITooLong                   ErrorCode = "uri_too_long"
	ErrorCodeUnsupportedMediaType         ErrorCode = "unsupported_media_type"
	ErrorCodeIdempotencyKeyReused         ErrorCode = "idempotency_key_reused"
	ErrorCodeRateLimited                  ErrorCode = "rate_limited"
	ErrorCodeInternalError                ErrorCode = "internal_error"
)

The error codes the API sends.

type EventCategory 

type EventCategory string

EventCategory is an event's category. 

const (
	EventCategorySession   EventCategory = "session"
	EventCategoryTask      EventCategory = "task"
	EventCategoryModel     EventCategory = "model"
	EventCategoryOutcome   EventCategory = "outcome"
	EventCategoryException EventCategory = "exception"
)

The event categories the API accepts. Any other value is refused by the API as a row error, invalid_value.

type EventInput 

type EventInput struct {
	// EventID deduplicates the event within the workspace.
	EventID string `json:"event_id,omitempty"`
	// Timestamp is when the event happened. It is sent in RFC 3339 form
	// with its offset. The zero time is sent, and refused by the API.
	Timestamp time.Time `json:"timestamp"`
	// AgentKey names the agent that acted. An agent not seen before is
	// created.
	AgentKey string `json:"agent_key"`
	// ClientKey names the client the event belongs to.
	ClientKey string `json:"client_key,omitempty"`
	// Category is the event's category.
	Category EventCategory `json:"category"`
	// EventType is what the agent did.
	EventType string `json:"event_type"`
	// OutcomeType is required when Category is EventCategoryOutcome.
	OutcomeType string `json:"outcome_type,omitempty"`
	// Quantity is the event's quantity. Zero means 1. It must be finite.
	Quantity float64 `json:"quantity,omitempty"`
	// Cost is in Currency, or the workspace's currency. Nil means absent.
	Cost *Decimal `json:"cost,omitempty"`
	// TokensIn is the input token count. Nil means absent.
	TokensIn *int64 `json:"tokens_in,omitempty"`
	// TokensOut is the output token count. Nil means absent.
	TokensOut *int64 `json:"tokens_out,omitempty"`
	// Model is the model the agent invoked.
	Model string `json:"model,omitempty"`
	// Currency is the ISO 4217 code of Cost. Empty means the workspace's
	// currency.
	Currency string `json:"currency,omitempty"`
	// Metadata is free-form. Empty means absent.
	Metadata map[string]any `json:"metadata,omitempty"`
}

EventInput is one event to ingest.

An empty optional string means absent, and is not sent. When EventID is empty, EventsService.Ingest generates one before the first attempt, so a retry never stores the event twice. A caller whose own delivery is at-least-once, such as a queue that may redeliver a message, should set EventID itself, for example to the message's id: an id the SDK generates does not survive the call.

type EventSource added in v0.2.0 

type EventSource string

EventSource How an event arrived: `api` for `POST /v1/events`, `csv` for a CSV import. 

const (
	EventSourceAPI EventSource = "api"
	EventSourceCSV EventSource = "csv"
)

Defines values for EventSource.

func (EventSource) Valid added in v0.2.0 

func (e EventSource) Valid() bool

Valid indicates whether the value is a known member of the EventSource enum.

type EventsService 

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

EventsService groups the operations on events. Reach it as client.Events.

func (EventsService) Format 

func (s EventsService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*EventsService) Ingest 

func (s *EventsService) Ingest(ctx context.Context, events []EventInput, opts ...RequestOption) (*IngestSummary, error)

Ingest sends events to the API, in as many batches as its limits require, and returns their combined outcome.

An empty list sends nothing and returns a summary of zeros. Every event without an EventID is given a random one first, so a retried batch never stores an event twice; the caller's slice is not modified. Batches hold at most 500 events and 4,000,000 bytes of body, and are sent one after another, in order, each with the client's retries. An event too large to send in any batch is not sent: it is reported in the summary as a rejected row with code too_large.

A partially accepted batch is a success: its refused events are counted in the summary's Rejected, and their problems listed in its Errors, as far as ErrorsTruncated allows. When a batch fails, Ingest sends nothing after it and returns an *IngestError holding the summary so far and the events not yet stored. An error from the client's token provider fails the batch the same way: it is the IngestError's cause, which errors.Is and errors.As see through. An event that cannot be encoded as JSON, such as one with a NaN Quantity or a string that is not valid UTF-8, ends the call before any request is sent, with an error that does not match ErrAllisall.

The options apply to every batch: WithRequestTimeout to each attempt, WithRequestMaxRetries to each batch's retries, and WithRequestHeader to every request. An option that is refused ends the call before any request is sent. Ingest never sends an Idempotency-Key: each event's event_id makes a retried batch safe.

func (*EventsService) ListForClient added in v0.2.0 

func (s *EventsService) ListForClient(ctx context.Context, clientID string, query ListClientEventsParams, opts ...RequestOption) (*Page[AttributedEvent, ClientEventList], error)

ListForClient lists the events behind a client's totals: the event drill-down, over the period query.From to query.To, which are required.

Pass query.Page or query.Cursor, not both; neither means page 1. A Page beyond the end returns no rows and the true total. The first page's Body holds Total and Period; walk every event from there with Page.All.

Needs the read scope. Operation listClientEvents.

type FieldError 

type FieldError struct {
	// Code names the problem. It may be a code this SDK does not list.
	Code      FieldErrorCode `json:"code"`
	Pointer   string         `json:"pointer,omitempty"`
	Parameter string         `json:"parameter,omitempty"`
	Header    string         `json:"header,omitempty"`
	Part      string         `json:"part,omitempty"`
	Column    string         `json:"column,omitempty"`
	Detail    string         `json:"detail"`
}

FieldError is one problem in a request. It carries exactly one of Pointer, Parameter, Header and Part; with Part, it may also carry Pointer or Column.

type FieldErrorCode 

type FieldErrorCode string

FieldErrorCode is the code of one field-level problem, or of an ingest row error. The set is open: the API may send a code this SDK does not list, and it is kept as it arrived. 

const (
	FieldErrorCodeRequired          FieldErrorCode = "required"
	FieldErrorCodeUnknownField      FieldErrorCode = "unknown_field"
	FieldErrorCodeImmutable         FieldErrorCode = "immutable"
	FieldErrorCodeInvalidType       FieldErrorCode = "invalid_type"
	FieldErrorCodeInvalidFormat     FieldErrorCode = "invalid_format"
	FieldErrorCodeInvalidValue      FieldErrorCode = "invalid_value"
	FieldErrorCodeTooLong           FieldErrorCode = "too_long"
	FieldErrorCodeTooMany           FieldErrorCode = "too_many"
	FieldErrorCodeOutOfRange        FieldErrorCode = "out_of_range"
	FieldErrorCodeTooPrecise        FieldErrorCode = "too_precise"
	FieldErrorCodeDuplicate         FieldErrorCode = "duplicate"
	FieldErrorCodeTooLarge          FieldErrorCode = "too_large"
	FieldErrorCodeMutuallyExclusive FieldErrorCode = "mutually_exclusive"
	FieldErrorCodeUnknownReference  FieldErrorCode = "unknown_reference"
	FieldErrorCodeClientKeyRequired FieldErrorCode = "client_key_required"
	FieldErrorCodeCurrencyMismatch  FieldErrorCode = "currency_mismatch"
)

The field-level codes the API sends. The SDK itself reports FieldErrorCodeTooLarge for an event too large to send in any batch.

type GetAgentParams added in v0.2.0 

type GetAgentParams struct {
	// From Start of a half-open range, inclusive. Absent means unbounded. Must not be after `to`, or it is refused with `out_of_range` on `from`. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	From *time.Time `form:"from,omitempty" json:"from,omitempty"`

	// To End of a half-open range, exclusive. Absent means unbounded. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	To *time.Time `form:"to,omitempty" json:"to,omitempty"`
}

GetAgentParams defines parameters for GetAgent.

type GetClientAnomaliesParams added in v0.2.0 

type GetClientAnomaliesParams struct {
	// From Start of the period, inclusive. Must not be after `to`, or it is refused with `out_of_range` on `from`. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	From time.Time `form:"from" json:"from"`

	// To End of the period, exclusive. Required: an open period would prorate to the current day, so the figure would change with the day it was read. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	To time.Time `form:"to" json:"to"`
}

GetClientAnomaliesParams defines parameters for GetClientAnomalies.

type GetClientCostParams added in v0.2.0 

type GetClientCostParams struct {
	// From Start of the period, inclusive. Must not be after `to`, or it is refused with `out_of_range` on `from`. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	From time.Time `form:"from" json:"from"`

	// To End of the period, exclusive. Required: an open period would prorate to the current day, so the figure would change with the day it was read. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	To time.Time `form:"to" json:"to"`
}

GetClientCostParams defines parameters for GetClientCost.

type GetClientRoiParams added in v0.2.0 

type GetClientRoiParams struct {
	// From Start of the period, inclusive. Must not be after `to`, or it is refused with `out_of_range` on `from`. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	From time.Time `form:"from" json:"from"`

	// To End of the period, exclusive. Required: an open period would prorate to the current day, so the figure would change with the day it was read. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	To time.Time `form:"to" json:"to"`
}

GetClientRoiParams defines parameters for GetClientRoi.

type GetClientValueParams added in v0.2.0 

type GetClientValueParams struct {
	// From Start of a half-open range, inclusive. Absent means unbounded. Must not be after `to`, or it is refused with `out_of_range` on `from`. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	From *time.Time `form:"from,omitempty" json:"from,omitempty"`

	// To End of a half-open range, exclusive. Absent means unbounded. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	To *time.Time `form:"to,omitempty" json:"to,omitempty"`
}

GetClientValueParams defines parameters for GetClientValue.

type GetDashboardParams added in v0.2.0 

type GetDashboardParams struct {
	// Month The calendar month, between `1900-01` and `9999-12`.
	Month string `form:"month" json:"month"`

	// Sort Sort key for `clients`. Every key defaults to ascending. A client with no value in the sorted column sorts after every client with one, in both directions. Ties are broken by `name`, A to Z and case-insensitively, whichever way the column runs, then by `id`. The sort orders `clients` only; `top_clients` keeps its own order.
	Sort *GetDashboardParamsSort `form:"sort,omitempty" json:"sort,omitempty"`

	// Dir Sort direction.
	Dir *GetDashboardParamsDir `form:"dir,omitempty" json:"dir,omitempty"`
}

GetDashboardParams defines parameters for GetDashboard.

type GetDashboardParamsDir added in v0.2.0 

type GetDashboardParamsDir string

GetDashboardParamsDir defines parameters for GetDashboard. 

const (
	GetDashboardParamsDirAsc  GetDashboardParamsDir = "asc"
	GetDashboardParamsDirDesc GetDashboardParamsDir = "desc"
)

Defines values for GetDashboardParamsDir.

func (GetDashboardParamsDir) Valid added in v0.2.0 

func (e GetDashboardParamsDir) Valid() bool

Valid indicates whether the value is a known member of the GetDashboardParamsDir enum.

type GetDashboardParamsSort added in v0.2.0 

type GetDashboardParamsSort string

GetDashboardParamsSort defines parameters for GetDashboard. 

const (
	GetDashboardParamsSortCostTotal   GetDashboardParamsSort = "cost_total"
	GetDashboardParamsSortName        GetDashboardParamsSort = "name"
	GetDashboardParamsSortRenewalDate GetDashboardParamsSort = "renewal_date"
	GetDashboardParamsSortRoi         GetDashboardParamsSort = "roi"
	GetDashboardParamsSortValueTotal  GetDashboardParamsSort = "value_total"
)

Defines values for GetDashboardParamsSort.

func (GetDashboardParamsSort) Valid added in v0.2.0 

func (e GetDashboardParamsSort) Valid() bool

Valid indicates whether the value is a known member of the GetDashboardParamsSort enum.

type Health added in v0.2.0 

type Health struct {
	Status HealthStatus `json:"status"`

	// Version The build version.
	Version string `json:"version"`
}

Health Liveness.

type HealthDirection added in v0.2.0 

type HealthDirection string

HealthDirection Which way a client's return moved against its own abutting prior published period, compared at one decimal place of percentage points. 

const (
	HealthDirectionDeclining HealthDirection = "declining"
	HealthDirectionImproving HealthDirection = "improving"
	HealthDirectionSteady    HealthDirection = "steady"
)

Defines values for HealthDirection.

func (HealthDirection) Valid added in v0.2.0 

func (e HealthDirection) Valid() bool

Valid indicates whether the value is a known member of the HealthDirection enum.

type HealthService added in v0.2.0 

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

HealthService groups the liveness check. Reach it as client.Health.

func (HealthService) Format added in v0.2.0 

func (s HealthService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*HealthService) Get added in v0.2.0 

func (s *HealthService) Get(ctx context.Context, opts ...RequestOption) (*Health, error)

Get checks liveness. It sends no credential, and does not call the client's token provider.

Operation getHealth.

type HealthStatus added in v0.2.0 

type HealthStatus string

HealthStatus defines model for Health.Status. 

const (
	HealthStatusOk HealthStatus = "ok"
)

Defines values for HealthStatus.

func (HealthStatus) Valid added in v0.2.0 

func (e HealthStatus) Valid() bool

Valid indicates whether the value is a known member of the HealthStatus enum.

type HealthUnavailable added in v0.2.0 

type HealthUnavailable string

HealthUnavailable Why a renewal row has no health signal. `never_published`: no published calculation. `no_prior_period`: nothing published abuts the latest period. `ratio_undefined`: a ratio on either side is undefined. 

const (
	HealthUnavailableNeverPublished HealthUnavailable = "never_published"
	HealthUnavailableNoPriorPeriod  HealthUnavailable = "no_prior_period"
	HealthUnavailableRatioUndefined HealthUnavailable = "ratio_undefined"
)

Defines values for HealthUnavailable.

func (HealthUnavailable) Valid added in v0.2.0 

func (e HealthUnavailable) Valid() bool

Valid indicates whether the value is a known member of the HealthUnavailable enum.

type IdempotentRequestOption added in v0.2.0 

type IdempotentRequestOption interface {
	// contains filtered or unexported methods
}

IdempotentRequestOption configures one call of an operation that takes an Idempotency-Key. Every RequestOption is one, and so is WithIdempotencyKey.

func WithIdempotencyKey added in v0.2.0 

func WithIdempotencyKey(key string) IdempotentRequestOption

WithIdempotencyKey sets the Idempotency-Key this call sends, in place of the one the SDK generates for each call. The key is sent as given, on every attempt. Set your own to make a create safe to repeat across process restarts.

A second call with the same key and the same request, within 24 hours, gets the first call's stored response. Only a successful response is stored, so a key whose first call failed can be sent again. The same key with a different body is refused with 422 idempotency_key_reused.

Only the operations that take an Idempotency-Key accept this option. A key holding a control character, such as a line feed, is refused before anything is sent, with an error that does not match ErrAllisall.

type ImportMapping added in v0.2.0 

type ImportMapping struct {
	// Columns Canonical field name to the file's column name. `timestamp`, `agent_key`, `event_type` and `category` must each be bound here or in `constants`. A column name is at most 256 bytes of UTF-8; a longer one is refused with `too_long` at its member. `maxLength` counts characters, so the server's byte limit is the tighter.
	Columns *map[string]string `json:"columns,omitempty"`

	// Constants Canonical field name to a value used for every row. `timestamp` and `event_id` cannot be constants. A field cannot be bound in both maps. A constant for `agent_key`, `client_key`, `event_type`, `outcome_type` or `model` holds at most 200 characters, counted as sent; a longer one refuses every row with `too_long`.
	Constants *map[string]string `json:"constants,omitempty"`

	// Delimiter The field delimiter. Default `,`.
	Delimiter *string `json:"delimiter,omitempty"`

	// Timezone An IANA zone for timestamps without an offset. Default `UTC`. `Local` is refused.
	//
	// Examples: Asia/Tokyo
	Timezone *string `json:"timezone,omitempty"`
}

ImportMapping How a CSV file maps onto canonical events. Each row's mapped values are held to the rules of `EventInput`. A `cost` with more than 6 decimal places is refused with `too_precise`, as on ingest. A `quantity` or `cost` cell must be a decimal number, `^[+-]?[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?$` after trimming, and a `tokens_in` or `tokens_out` cell an integer, `^[+-]?[0-9]+$`; anything else, hexadecimal, underscores, `Inf` and `NaN` included, is refused with `invalid_format`. An empty cell is not provided. An empty `currency` cell declares no currency. An `event_id`, `agent_key`, `client_key`, `event_type`, `outcome_type` or `model` value holds at most 200 characters, as on ingest. A cell is counted after trimming, and a constant as given. A longer value refuses its row with `too_long` at its column, or with a `null` column for a constant. A cell bound to `event_id`, `agent_key`, `client_key`, `category`, `event_type`, `outcome_type` or `model` that is not valid UTF-8 refuses its row with `invalid_format` at its column, as one holding U+0000 does.

type ImportPreview added in v0.2.0 

type ImportPreview struct {
	// Errors One entry per problem, ascending by `row`. A row's entries follow the order its checks run: first whether the record can be read as CSV, then each field's cell and rules in field order, then the attribution guard. A row that fails one check is not checked by the later ones. At most 1,000 in all: the first 1,000 in that order, which may end partway through a row. A CSV row has at most 13 entries, one for each field a mapping can bind.
	Errors []ImportRowError `json:"errors"`

	// ErrorsTruncated Whether `errors` omits any problem because of the 1,000 cap. The counts always cover the whole file.
	ErrorsTruncated bool `json:"errors_truncated"`

	// IgnoredColumns The first 100 columns the mapping does not bind, in the header's order, left to right. A blank header cell is a column too, listed as `""`. `ignored_columns_omitted` counts the rest.
	IgnoredColumns []string `json:"ignored_columns"`

	// IgnoredColumnsOmitted How many columns the mapping does not bind beyond the 100 in `ignored_columns`. `0` when the list is complete.
	IgnoredColumnsOmitted int `json:"ignored_columns_omitted"`

	// Preview The first 20 data rows, in file order, broken rows included.
	Preview []PreviewRow `json:"preview"`

	// Rejected Rows the file would reject, counted once each however many problems they have.
	Rejected        int     `json:"rejected"`
	TimezoneWarning *string `json:"timezone_warning"`
	TotalRows       int     `json:"total_rows"`
	Valid           int     `json:"valid"`
}

ImportPreview What committing the file would do. Nothing is written.

type ImportResult added in v0.2.0 

type ImportResult struct {
	Accepted   int `json:"accepted"`
	Duplicates int `json:"duplicates"`

	// Errors As on the preview: one entry per problem, by `row`, at most 1,000 in all. `[]` when no row was rejected.
	Errors []ImportRowError `json:"errors"`

	// ErrorsTruncated Whether `errors` omits any problem, as on the preview.
	ErrorsTruncated bool   `json:"errors_truncated"`
	ImportBatchID   string `json:"import_batch_id"`

	// Rejected Rows rejected, counted once each however many problems they have.
	Rejected int `json:"rejected"`
}

ImportResult The outcome of a CSV import. Partial acceptance is a success.

type ImportRowError added in v0.2.0 

type ImportRowError struct {
	// Code The field-level code of one `errors` entry, or of an ingest or CSV row error. The vocabulary is open: new codes are additive.
	Code   FieldErrorCode `json:"code"`
	Column *string        `json:"column"`
	Detail string         `json:"detail"`

	// Row The one-based line number in the file, counting the header.
	Row int `json:"row"`
}

ImportRowError One problem with a rejected CSV row. A row with several problems has one entry for each, all carrying its `row`.

type ImportUpload added in v0.2.0 

type ImportUpload struct {
	// Mapping is sent as the first part, named mapping: its JSON, typed
	// application/json, with the file name mapping.json.
	Mapping ImportMapping
	// File is sent as the second part, named file, typed text/csv. It is
	// read from its position when the call is made to its end, and read
	// again from that position for each retry, so it is never held in
	// memory. Its position is unspecified after the call. A reader that
	// cannot seek, such as an *os.File opened on a pipe, is refused before
	// anything is sent; copy a one-shot stream to a temporary file or a
	// bytes.Reader first.
	File io.ReadSeeker
	// Filename is the file name the import records. When empty, it is the
	// base of the file's own name, for a File with a Name() string method
	// such as an *os.File, and otherwise upload.csv.
	Filename string
}

ImportUpload is a CSV import: how the file's columns map to event members, and the file itself. It is sent as a form of two parts, the mapping and then the file.

type ImportsService added in v0.2.0 

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

ImportsService groups the CSV import operations. Reach it as client.Imports.

func (*ImportsService) Commit added in v0.2.0 

func (s *ImportsService) Commit(ctx context.Context, upload ImportUpload, opts ...IdempotentRequestOption) (*ImportResult, error)

Commit imports a CSV file: it stores the file's valid rows and records an import batch. A problem with one row rejects that row only. The result lists the problems of the rejected rows, one entry of Errors per problem, up to the first 1,000; ErrorsTruncated says when more were omitted, and the counts always cover the whole file. Events deduplicate as they do on ingest.

Every attempt of the call sends one Idempotency-Key, so a retry cannot record a second import batch.

Needs the ingest scope. Operation commitImport.

func (ImportsService) Format added in v0.2.0 

func (s ImportsService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*ImportsService) Preview added in v0.2.0 

func (s *ImportsService) Preview(ctx context.Context, upload ImportUpload, opts ...RequestOption) (*ImportPreview, error)

Preview previews a CSV import: it parses, maps and validates the file exactly as ImportsService.Commit would, and writes nothing.

Never retried, although it writes nothing; repeat the call to try again.

Needs the ingest scope. Operation previewImport.

type IngestError 

type IngestError struct {
	// Summary is the combined outcome of the batches that succeeded, and
	// of every event too large to send.
	Summary *IngestSummary
	// Remaining holds copies of every event from the failed batch onward,
	// each with the event_id it was given. It never holds an event too
	// large to send.
	Remaining []EventInput
	// RemainingFrom is the index, in the caller's list, of the first event
	// in Remaining.
	RemainingFrom int
	// Err is the cause: an [*APIError], a [*ConnectionError], the
	// context's error when the caller cancelled, or the error the token
	// provider returned, unchanged.
	Err error
}

IngestError is a batch that failed inside EventsService.Ingest. The batches before it succeeded; it and every batch after it were not stored by this call, except that the failed batch may have been stored if its response was lost.

To recover, send Remaining again: each event in it carries the event_id it was first sent with, so any the failed batch stored come back as duplicates.

func (*IngestError) Error 

func (e *IngestError) Error() string

Error describes the error.

func (*IngestError) Is 

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

Is reports whether target is ErrAllisall.

func (*IngestError) Unwrap 

func (e *IngestError) Unwrap() error

Unwrap returns the cause.

type IngestRowError 

type IngestRowError struct {
	// Index is the event's zero-based position in the caller's list.
	Index int `json:"index"`
	// Code names the problem. It may be a code this SDK does not list.
	Code FieldErrorCode `json:"code"`
	// Pointer is an RFC 6901 JSON Pointer that starts /events/<Index>.
	Pointer string `json:"pointer"`
	// Detail is human text. Its wording may change at any time.
	Detail string `json:"detail"`
}

IngestRowError is one problem with a rejected event.

type IngestSummary 

type IngestSummary struct {
	// Accepted is the number of events stored.
	Accepted int
	// Duplicates is the number of events already stored, by event_id or
	// content hash. After a retry, an event the first attempt stored is
	// counted here.
	Duplicates int
	// Rejected is the number of events refused, each counted once.
	Rejected int
	// Errors holds one entry per problem, ascending by Index, which is the
	// event's position in the caller's list. When ErrorsTruncated is true,
	// some problems have no entry, and a rejected event may have none.
	Errors []IngestRowError
	// ErrorsTruncated reports whether Errors omits any problem. The API
	// lists at most 20 problems of one event, and at most 1,000,000 bytes
	// of entries for one batch. The counts always cover every event.
	ErrorsTruncated bool
	// Batches is the number of batches sent.
	Batches int
}

IngestSummary is the combined outcome of one EventsService.Ingest call, over the caller's whole list of events.

Accepted + Duplicates + Rejected equals the number of events passed.

type ListAgentsParams added in v0.2.0 

type ListAgentsParams struct {
	// Limit Page size, 1 to 200. A value outside the range is refused with `out_of_range`, never clamped.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Cursor `next_cursor` from the previous page. Valid only with the filters and sort it was issued under; otherwise refused with `invalid_value`. An empty value is refused with `invalid_format`, like any empty query parameter. `limit` may change between pages.
	Cursor *string `form:"cursor,omitempty" json:"cursor,omitempty"`
}

ListAgentsParams defines parameters for ListAgents.

type ListCalculationReportsParams added in v0.2.0 

type ListCalculationReportsParams struct {
	// Limit Page size, 1 to 200. A value outside the range is refused with `out_of_range`, never clamped.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Cursor `next_cursor` from the previous page. Valid only with the filters and sort it was issued under; otherwise refused with `invalid_value`. An empty value is refused with `invalid_format`, like any empty query parameter. `limit` may change between pages.
	Cursor *string `form:"cursor,omitempty" json:"cursor,omitempty"`
}

ListCalculationReportsParams defines parameters for ListCalculationReports.

type ListClientCalculationsParams added in v0.2.0 

type ListClientCalculationsParams struct {
	// Limit Page size, 1 to 200. A value outside the range is refused with `out_of_range`, never clamped.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Cursor `next_cursor` from the previous page. Valid only with the filters and sort it was issued under; otherwise refused with `invalid_value`. An empty value is refused with `invalid_format`, like any empty query parameter. `limit` may change between pages.
	Cursor *string `form:"cursor,omitempty" json:"cursor,omitempty"`
}

ListClientCalculationsParams defines parameters for ListClientCalculations.

type ListClientEventsParams added in v0.2.0 

type ListClientEventsParams struct {
	// From Start of the period, inclusive. Must not be after `to`, or it is refused with `out_of_range` on `from`. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	From time.Time `form:"from" json:"from"`

	// To End of the period, exclusive. Required: an open period would prorate to the current day, so the figure would change with the day it was read. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	To time.Time `form:"to" json:"to"`

	// Category Only events of this category.
	Category *EventCategory `form:"category,omitempty" json:"category,omitempty"`

	// OutcomeType Only events with this outcome type. An empty value, or one with leading or trailing whitespace, is refused with `invalid_format`.
	OutcomeType *string `form:"outcome_type,omitempty" json:"outcome_type,omitempty"`

	// AgentID Only events from this agent. An id in any spelling but the RFC 9562 string form is refused with `invalid_format`.
	AgentID *string `form:"agent_id,omitempty" json:"agent_id,omitempty"`

	// Sort Sort key. `timestamp` and `cost` default to descending; `agent_name`, `attributed_by` and `source` to ascending. `attributed_by` sorts events that carried a client key apart from those attributed by solo-agent assignment. `cost` puts events without a cost last in both directions.
	Sort *ListClientEventsParamsSort `form:"sort,omitempty" json:"sort,omitempty"`

	// Dir Sort direction. Absent means the sort key's default.
	Dir *ListClientEventsParamsDir `form:"dir,omitempty" json:"dir,omitempty"`

	// Limit Page size, 1 to 200. A value outside the range is refused with `out_of_range`, never clamped.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Cursor `next_cursor` from the previous page. Valid only with the filters and sort it was issued under; otherwise refused with `invalid_value`. An empty value is refused with `invalid_format`, like any empty query parameter. `limit` may change between pages.
	Cursor *string `form:"cursor,omitempty" json:"cursor,omitempty"`

	// Page Page number, from 1: the offset `(page − 1) × limit`. Not with `cursor`: both together are refused with `mutually_exclusive` on `cursor`. The offset must not exceed 10,000,000, the most a cursor holds; a larger one is refused with `out_of_range` on `page`. A page whose next offset would exceed 10,000,000 has `has_more` false and a null `next_cursor`, even if rows remain.
	Page *int `form:"page,omitempty" json:"page,omitempty"`
}

ListClientEventsParams defines parameters for ListClientEvents.

type ListClientEventsParamsDir added in v0.2.0 

type ListClientEventsParamsDir string

ListClientEventsParamsDir defines parameters for ListClientEvents. 

const (
	ListClientEventsParamsDirAsc  ListClientEventsParamsDir = "asc"
	ListClientEventsParamsDirDesc ListClientEventsParamsDir = "desc"
)

Defines values for ListClientEventsParamsDir.

func (ListClientEventsParamsDir) Valid added in v0.2.0 

func (e ListClientEventsParamsDir) Valid() bool

Valid indicates whether the value is a known member of the ListClientEventsParamsDir enum.

type ListClientEventsParamsSort added in v0.2.0 

type ListClientEventsParamsSort string

ListClientEventsParamsSort defines parameters for ListClientEvents. 

const (
	ListClientEventsParamsSortAgentName    ListClientEventsParamsSort = "agent_name"
	ListClientEventsParamsSortAttributedBy ListClientEventsParamsSort = "attributed_by"
	ListClientEventsParamsSortCost         ListClientEventsParamsSort = "cost"
	ListClientEventsParamsSortSource       ListClientEventsParamsSort = "source"
	ListClientEventsParamsSortTimestamp    ListClientEventsParamsSort = "timestamp"
)

Defines values for ListClientEventsParamsSort.

func (ListClientEventsParamsSort) Valid added in v0.2.0 

func (e ListClientEventsParamsSort) Valid() bool

Valid indicates whether the value is a known member of the ListClientEventsParamsSort enum.

type ListClientOutcomeTypesParams added in v0.2.0 

type ListClientOutcomeTypesParams struct {
	// From Start of a half-open range, inclusive. Absent means unbounded. Must not be after `to`, or it is refused with `out_of_range` on `from`. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	From *time.Time `form:"from,omitempty" json:"from,omitempty"`

	// To End of a half-open range, exclusive. Absent means unbounded. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	To *time.Time `form:"to,omitempty" json:"to,omitempty"`

	// Limit Page size, 1 to 200. A value outside the range is refused with `out_of_range`, never clamped.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Cursor `next_cursor` from the previous page. Valid only with the filters and sort it was issued under; otherwise refused with `invalid_value`. An empty value is refused with `invalid_format`, like any empty query parameter. `limit` may change between pages.
	Cursor *string `form:"cursor,omitempty" json:"cursor,omitempty"`
}

ListClientOutcomeTypesParams defines parameters for ListClientOutcomeTypes.

type ListClientsParams added in v0.2.0 

type ListClientsParams struct {
	// Limit Page size, 1 to 200. A value outside the range is refused with `out_of_range`, never clamped.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Cursor `next_cursor` from the previous page. Valid only with the filters and sort it was issued under; otherwise refused with `invalid_value`. An empty value is refused with `invalid_format`, like any empty query parameter. `limit` may change between pages.
	Cursor *string `form:"cursor,omitempty" json:"cursor,omitempty"`
}

ListClientsParams defines parameters for ListClients.

type ListCostLineItemsParams added in v0.2.0 

type ListCostLineItemsParams struct {
	// Limit Page size, 1 to 200. A value outside the range is refused with `out_of_range`, never clamped.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Cursor `next_cursor` from the previous page. Valid only with the filters and sort it was issued under; otherwise refused with `invalid_value`. An empty value is refused with `invalid_format`, like any empty query parameter. `limit` may change between pages.
	Cursor *string `form:"cursor,omitempty" json:"cursor,omitempty"`
}

ListCostLineItemsParams defines parameters for ListCostLineItems.

type ListOutcomeTypesParams added in v0.2.0 

type ListOutcomeTypesParams struct {
	// From Start of a half-open range, inclusive. Absent means unbounded. Must not be after `to`, or it is refused with `out_of_range` on `from`. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	From *time.Time `form:"from,omitempty" json:"from,omitempty"`

	// To End of a half-open range, exclusive. Absent means unbounded. Each sent bound must be at or after `1900-01-01T00:00:00Z` and before `10000-01-01T00:00:00Z`; otherwise it is refused with `out_of_range` on its own parameter. Digits below a microsecond are dropped before any check. When both bounds are sent, `to` may be at most 731 days after `from`; a longer period is refused with `out_of_range` on `from`.
	To *time.Time `form:"to,omitempty" json:"to,omitempty"`

	// Limit Page size, 1 to 200. A value outside the range is refused with `out_of_range`, never clamped.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Cursor `next_cursor` from the previous page. Valid only with the filters and sort it was issued under; otherwise refused with `invalid_value`. An empty value is refused with `invalid_format`, like any empty query parameter. `limit` may change between pages.
	Cursor *string `form:"cursor,omitempty" json:"cursor,omitempty"`
}

ListOutcomeTypesParams defines parameters for ListOutcomeTypes.

type ListRenewalsParams added in v0.2.0 

type ListRenewalsParams struct {
	// Limit Page size, 1 to 200. A value outside the range is refused with `out_of_range`, never clamped.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Cursor `next_cursor` from the previous page. Valid only with the filters and sort it was issued under; otherwise refused with `invalid_value`. An empty value is refused with `invalid_format`, like any empty query parameter. `limit` may change between pages.
	Cursor *string `form:"cursor,omitempty" json:"cursor,omitempty"`
}

ListRenewalsParams defines parameters for ListRenewals.

type ListValueModelsParams added in v0.2.0 

type ListValueModelsParams struct {
	// Limit Page size, 1 to 200. A value outside the range is refused with `out_of_range`, never clamped.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Cursor `next_cursor` from the previous page. Valid only with the filters and sort it was issued under; otherwise refused with `invalid_value`. An empty value is refused with `invalid_format`, like any empty query parameter. `limit` may change between pages.
	Cursor *string `form:"cursor,omitempty" json:"cursor,omitempty"`
}

ListValueModelsParams defines parameters for ListValueModels.

type ListValueTemplatesParams added in v0.2.0 

type ListValueTemplatesParams struct {
	// Limit Page size, 1 to 200. A value outside the range is refused with `out_of_range`, never clamped.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Cursor `next_cursor` from the previous page. Valid only with the filters and sort it was issued under; otherwise refused with `invalid_value`. An empty value is refused with `invalid_format`, like any empty query parameter. `limit` may change between pages.
	Cursor *string `form:"cursor,omitempty" json:"cursor,omitempty"`
}

ListValueTemplatesParams defines parameters for ListValueTemplates.

type ManualCostLine added in v0.2.0 

type ManualCostLine struct {
	// CoveredDays Days of the period the charge covers.
	CoveredDays   int     `json:"covered_days"`
	ID            string  `json:"id"`
	Label         string  `json:"label"`
	MonthlyAmount Decimal `json:"monthly_amount"`

	// Target What a cost line item is charged to: a client or an agent.
	Target CostTarget `json:"target"`

	// Total The prorated amount for the period.
	Total Decimal `json:"total"`
}

ManualCostLine A cost line item prorated over the period.

type ModelRate added in v0.2.0 

type ModelRate struct {
	// InputPer1K The price of 1,000 input tokens, with at most 9 decimal places.
	InputPer1K Decimal `json:"input_per_1k"`

	// Model The model name events carry in `model`. Matched case-insensitively, after trimming.
	Model string `json:"model"`

	// OutputPer1K The price of 1,000 output tokens, with at most 9 decimal places.
	OutputPer1K Decimal `json:"output_per_1k"`
}

ModelRate One model's token prices.

type ModelRateInput added in v0.2.0 

type ModelRateInput struct {
	// InputPer1K The price of 1,000 input tokens. At least 0 and below 100,000,000, with at most 9 decimal places; more is refused with `too_precise`, never rounded. A rate is not money: $0.000001 per million tokens is 0.000000001 per 1,000. Money computed from a rate keeps 6 decimal places, as an event's `cost` does.
	InputPer1K Decimal `json:"input_per_1k"`

	// Model 1 to 200 characters. A name blank after trimming is refused with `required`, and one holding U+0000 with `invalid_format`. Unique within the table after trimming and lower-casing: a name equal to an earlier entry's is refused with `duplicate` at the later entry. Stored as sent.
	Model string `json:"model"`

	// OutputPer1K The price of 1,000 output tokens. At least 0 and below 100,000,000, with at most 9 decimal places; more is refused with `too_precise`, never rounded. A rate is not money: $0.000001 per million tokens is 0.000000001 per 1,000. Money computed from a rate keeps 6 decimal places, as an event's `cost` does.
	OutputPer1K Decimal `json:"output_per_1k"`
}

ModelRateInput defines model for ModelRateInput.

type Nullable added in v0.2.0 

type Nullable[T any] struct {
	// contains filtered or unexported fields
}

Nullable is a member of a merge patch that can be cleared. It holds one of three states:

  • absent, the zero Nullable: the member is not sent, and the API leaves the value as it is;
  • null, from Null: the member is sent as null, and the API clears the value;
  • a value, from NewNullable: the member is sent with that value.

A struct member of this type is tagged omitzero, which leaves out an absent member. Outside such a member, an absent Nullable is written as null.

func NewNullable added in v0.2.0 

func NewNullable[T any](v T) Nullable[T]

NewNullable returns a Nullable holding v.

func Null added in v0.2.0 

func Null[T any]() Nullable[T]

Null returns a Nullable holding an explicit null.

func (Nullable[T]) Get added in v0.2.0 

func (n Nullable[T]) Get() (T, bool)

Get returns the value, and true only when one is set. When n is absent or null, it returns the zero T and false.

func (Nullable[T]) IsNull added in v0.2.0 

func (n Nullable[T]) IsNull() bool

IsNull reports whether n holds an explicit null.

func (Nullable[T]) IsZero added in v0.2.0 

func (n Nullable[T]) IsZero() bool

IsZero reports whether n is absent. The omitzero tag option reads it, so an absent member is not sent.

func (Nullable[T]) MarshalJSON added in v0.2.0 

func (n Nullable[T]) MarshalJSON() ([]byte, error)

MarshalJSON writes null, or the value's own JSON.

func (*Nullable[T]) UnmarshalJSON added in v0.2.0 

func (n *Nullable[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON reads null as an explicit null, and anything else as a set value.

type Option 

type Option func(*settings)

Option configures a Client built by NewClient.

func WithAPIKey 

func WithAPIKey(key string) Option

WithAPIKey sets the API key the client sends. Without it, and without WithTokenProvider, the client reads AIA_API_KEY from the environment. Leading and trailing white space is removed from the key, as from AIA_API_KEY and from each token a provider returns, so a key read with a trailing newline works. A key that is empty after that counts as missing. What remains must be printable ASCII, U+0021 to U+007E: an inner space, a control character or any non-ASCII character is refused.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL sets the API's base URL, an absolute http or https URL. A path it carries is kept: "https://example.test/api" sends ingest to "https://example.test/api/v1/events". Without it, the client reads AIA_BASE_URL from the environment, then uses https://api.allisai.ai.

func WithHTTPClient 

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets the *http.Client the client sends requests with. The SDK never modifies it, so its own redirect policy applies: a client that follows redirects, as http.Client does by default, may send the request and its Authorization header on to the redirect's target. Without it, or with nil, the client uses a new http.Client with the default transport that follows no redirect, so a 3xx response is returned as an *APIError and is not retried.

func WithHeader added in v0.2.0 

func WithHeader(name, value string) Option

WithHeader sends a header on every request. A header of the same name, in any case, from the SDK, such as User-Agent, or from an earlier WithHeader, is replaced, so one header is sent; a call's own WithRequestHeader replaces it in turn.

It may not name Authorization, Content-Type, Idempotency-Key or X-Request-Id, which the SDK sets, nor Host, Content-Length or Transfer-Encoding, which net/http sets. That, a name that is not an HTTP token, or a value holding a control character such as a line feed, makes NewClient fail.

func WithMaxRetries 

func WithMaxRetries(n int) Option

WithMaxRetries sets how many times a failed attempt is retried; the default is 2. Zero sends one attempt.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout bounds each attempt, not the whole call; the default is 60 seconds. Bound the whole call with the context passed to each method.

func WithTokenProvider 

func WithTokenProvider(provider func(ctx context.Context) (string, error)) Option

WithTokenProvider sets a function the client calls before every attempt, retries included, for the bearer token to send. An error it returns is not retried. In EventsService.Ingest it fails the batch: the call returns an *IngestError whose cause is the provider's error, reachable with errors.Is and errors.As.

A provider may supply an API key fetched at run time, for example from a secret store, or a session token: every operation but ingest accepts one, and acts as the session's user. Ingest takes API keys only, and answers a session token with 401 unauthenticated.

type OutcomeTypeList added in v0.2.0 

type OutcomeTypeList struct {
	// Data One page of items, at most `limit`, in the documented order.
	Data []OutcomeTypeUsage `json:"data"`

	// HasMore Whether another page exists.
	HasMore    bool    `json:"has_more"`
	NextCursor *string `json:"next_cursor"`
}

OutcomeTypeList Outcome types by summed quantity, largest first, then by name.

type OutcomeTypeUsage added in v0.2.0 

type OutcomeTypeUsage struct {
	Events int `json:"events"`

	// OutcomeType As events carry it.
	OutcomeType string `json:"outcome_type"`
	Priced      *bool  `json:"priced"`

	// Quantity The summed event quantity.
	Quantity float64 `json:"quantity"`
}

OutcomeTypeUsage An outcome type seen in events, with its volume.

type OutcomeTypesService added in v0.2.0 

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

OutcomeTypesService groups the operations on outcome types. Reach it as client.OutcomeTypes.

func (OutcomeTypesService) Format added in v0.2.0 

func (s OutcomeTypesService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*OutcomeTypesService) List added in v0.2.0 

func (s *OutcomeTypesService) List(ctx context.Context, query *ListOutcomeTypesParams, opts ...RequestOption) (*Page[OutcomeTypeUsage, OutcomeTypeList], error)

List lists the workspace's outcome types, and returns the first page. Walk every outcome type of every page with Page.All. A nil query sends none.

Needs the read scope. Operation listOutcomeTypes.

func (*OutcomeTypesService) ListForClient added in v0.2.0 

func (s *OutcomeTypesService) ListForClient(ctx context.Context, clientID string, query *ListClientOutcomeTypesParams, opts ...RequestOption) (*Page[OutcomeTypeUsage, OutcomeTypeList], error)

ListForClient lists a client's outcome types, and returns the first page. Walk every outcome type of every page with Page.All. A nil query sends none.

Needs the read scope. Operation listClientOutcomeTypes.

type Page added in v0.2.0 

type Page[T, B any] struct {
	// Data holds the page's items.
	Data []T
	// Body is the whole decoded response, with any members the list
	// carries beside its items, such as a ClientEventList's Total.
	Body B
	// contains filtered or unexported fields
}

Page is one page of a list: its items, and the whole response they came in. T is the item type and B the list's response type, such as Page[ClientRecord, ClientList].

The options of the call that fetched the first page apply to every page fetched from it.

func (*Page[T, B]) All added in v0.2.0 

func (p *Page[T, B]) All(ctx context.Context) iter.Seq2[T, error]

All yields every item of this page, then of each page after it, fetching each page when the loop reaches it. A failed request yields one pair of the zero item and the error, and the walk ends; the items already yielded stay yielded. Leaving the loop early fetches nothing more.

A page whose next_cursor was already sent earlier in the walk would repeat pages without end, so it ends the walk with an *APIError carrying that page's status and no problem. NextPage refuses it the same way.

The API does not remove duplicates: a keyset list can show a row twice when its sort value changes during the walk, and an offset list can skip or repeat rows when rows are added.

func (Page[T, B]) Format added in v0.2.0 

func (p Page[T, B]) Format(f fmt.State, _ rune)

Format prints the page for every fmt verb without the client it fetches the next page with, which holds the credential.

func (*Page[T, B]) HasNextPage added in v0.2.0 

func (p *Page[T, B]) HasNextPage() bool

HasNextPage reports whether another page follows this one.

func (*Page[T, B]) NextPage added in v0.2.0 

func (p *Page[T, B]) NextPage(ctx context.Context, opts ...RequestOption) (*Page[T, B], error)

NextPage fetches the page after this one. Its options apply to that one request, laid over the options of the call that fetched the first page: an option set here replaces the call's, and a header set here replaces the call's header of the same name. The page it returns goes back to the call's options.

On the last page it returns an error matching ErrAllisall and sends nothing.

type Period added in v0.2.0 

type Period struct {
	From *time.Time `json:"from"`
	To   *time.Time `json:"to"`
}

Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.

type PeriodInput added in v0.2.0 

type PeriodInput struct {
	From time.Time `json:"from"`
	To   time.Time `json:"to"`
}

PeriodInput A half-open range of instants, `[from, to)`. Both sides are required.

type PortfolioClient added in v0.2.0 

type PortfolioClient struct {
	ClientID    string                    `json:"client_id"`
	CostTotal   *Decimal                  `json:"cost_total"`
	Name        string                    `json:"name"`
	Reason      *PortfolioExclusionReason `json:"reason"`
	RenewalDate *string                   `json:"renewal_date"`
	Roi         *float64                  `json:"roi"`

	// Status A client's lifecycle status.
	Status     ClientStatus `json:"status"`
	ValueTotal *Decimal     `json:"value_total"`
}

PortfolioClient One client's published figure for the month. `reason` is `null` exactly when the client is counted in the totals.

type PortfolioExclusionReason added in v0.2.0 

type PortfolioExclusionReason string

PortfolioExclusionReason Why a client is not counted in the dashboard totals. `not_published_this_period`: it has published, but not for this month. `never_published`: no published calculation for any period. `published_off_grid`: a published calculation overlaps the month without equalling it. `no_value_model` and `zero_cost`: the published figure has no ratio. 

const (
	PortfolioExclusionReasonNeverPublished         PortfolioExclusionReason = "never_published"
	PortfolioExclusionReasonNoValueModel           PortfolioExclusionReason = "no_value_model"
	PortfolioExclusionReasonNotPublishedThisPeriod PortfolioExclusionReason = "not_published_this_period"
	PortfolioExclusionReasonPublishedOffGrid       PortfolioExclusionReason = "published_off_grid"
	PortfolioExclusionReasonZeroCost               PortfolioExclusionReason = "zero_cost"
)

Defines values for PortfolioExclusionReason.

func (PortfolioExclusionReason) Valid added in v0.2.0 

func (e PortfolioExclusionReason) Valid() bool

Valid indicates whether the value is a known member of the PortfolioExclusionReason enum.

type PreviewEvent added in v0.2.0 

type PreviewEvent struct {
	AgentKey string `json:"agent_key"`

	// Category An event category.
	Category    EventCategory           `json:"category"`
	ClientKey   *string                 `json:"client_key"`
	Cost        *Decimal                `json:"cost"`
	Currency    *string                 `json:"currency"`
	EventID     *string                 `json:"event_id"`
	EventType   string                  `json:"event_type"`
	Metadata    *map[string]interface{} `json:"metadata"`
	Model       *string                 `json:"model"`
	OutcomeType *string                 `json:"outcome_type"`
	Quantity    float64                 `json:"quantity"`
	Timestamp   time.Time               `json:"timestamp"`
	TokensIn    *int                    `json:"tokens_in"`
	TokensOut   *int                    `json:"tokens_out"`
}

PreviewEvent A mapped event as commit would store it. Every field is present; an unset one is `null`.

type PreviewRow added in v0.2.0 

type PreviewRow struct {
	// Errors The row's problems, in the order the row's entries take in the response's `errors`. `[]` for a valid row. At most 13: one for each field a mapping can bind.
	Errors []ImportRowError `json:"errors"`
	Event  *PreviewEvent    `json:"event"`

	// Row The one-based line number, counting the header.
	Row int `json:"row"`
}

PreviewRow One of the first 20 data rows. A valid row has its `event` and `errors` `[]`; a rejected row has `event` `null` and 1 to 13 `errors`.

type PriceTable added in v0.2.0 

type PriceTable struct {
	Currency string `json:"currency"`

	// Models At most 200. Ascending by `model`, compared case-insensitively.
	Models []ModelRate `json:"models"`
}

PriceTable The workspace's token prices for valuing model events that carry tokens and no cost.

type PriceTableSet added in v0.2.0 

type PriceTableSet struct {
	// Currency Optional, so a caller can `PUT` back the table it read. It cannot change the currency: when sent it must equal the workspace currency, or the request is refused with `400` `validation_failed` and the field code `currency_mismatch` at `/currency`.
	Currency *string `json:"currency,omitempty"`

	// Models The complete table, at most 200. `[]` empties it. A longer array is refused at its 201st entry with one `too_many` at `/models`, before any entry is validated.
	Models []ModelRateInput `json:"models"`
}

PriceTableSet defines model for PriceTableSet.

type Problem 

type Problem struct {
	Type   string `json:"type"`
	Title  string `json:"title"`
	Status int    `json:"status"`
	Detail string `json:"detail"`
	// Code names the error. It may be a code this SDK does not list; fall
	// back on Status for one you do not recognise.
	Code ErrorCode `json:"code"`
	// RequestID is the response's X-Request-Id, to quote when reporting
	// the problem.
	RequestID string `json:"request_id"`
	// Errors is present only with ErrorCodeValidationFailed.
	Errors []FieldError `json:"errors,omitempty"`
}

Problem is an RFC 9457 problem document, the body of every error response from the API.

type PublicReport added in v0.2.0 

type PublicReport struct {
	ClientName string `json:"client_name"`
	ComparedTo *struct {
		CostTotal Decimal `json:"cost_total"`

		// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
		Period     Period   `json:"period"`
		Roi        *float64 `json:"roi"`
		ValueTotal *Decimal `json:"value_total"`
	} `json:"compared_to"`
	Currency string `json:"currency"`

	// Disclosures The included findings only, in report order. At most 12: each kind appears at most once.
	Disclosures []Disclosure `json:"disclosures"`
	MinorUnits  int          `json:"minor_units"`

	// Note Free text, `""` when empty.
	Note string `json:"note"`

	// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
	Period Period `json:"period"`

	// Snapshot The calculation's snapshot, narrowed to what a recipient sees.
	Snapshot struct {
		Cost struct {
			Manual      Decimal `json:"manual"`
			PassThrough Decimal `json:"pass_through"`
			TokenValued Decimal `json:"token_valued"`
			Total       Decimal `json:"total"`
		} `json:"cost"`
		Currency   string `json:"currency"`
		MinorUnits int    `json:"minor_units"`

		// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
		Period Period `json:"period"`

		// Ratios The two return ratios. Both are `null` together, exactly when `undefined_reason` is set.
		Ratios          Ratios `json:"ratios"`
		SnapshotVersion int    `json:"snapshot_version"`
		Value           struct {
			Lines      []ValueLine `json:"lines"`
			Total      *Decimal    `json:"total"`
			ValueModel *struct {
				Name    string `json:"name"`
				Version int    `json:"version"`
			} `json:"value_model"`
		} `json:"value"`
	} `json:"snapshot"`
	WorkspaceName string `json:"workspace_name"`
}

PublicReport A shared report as its recipient reads it.

type Ratios added in v0.2.0 

type Ratios struct {
	Roi             *float64         `json:"roi"`
	UndefinedReason *UndefinedReason `json:"undefined_reason"`
	ValueToCost     *float64         `json:"value_to_cost"`
}

Ratios The two return ratios. Both are `null` together, exactly when `undefined_reason` is set.

type Renewal added in v0.2.0 

type Renewal struct {
	ClientID string `json:"client_id"`
	Health   *struct {
		CurrentRoi float64 `json:"current_roi"`

		// DeltaPoints The change in percentage points, one decimal place.
		DeltaPoints float64 `json:"delta_points"`

		// Direction Which way a client's return moved against its own abutting prior published period, compared at one decimal place of percentage points.
		Direction HealthDirection `json:"direction"`
		PriorRoi  float64         `json:"prior_roi"`
	} `json:"health"`
	Name        string             `json:"name"`
	Period      *Period            `json:"period"`
	PriorPeriod *string            `json:"prior_period"`
	RenewalDate string             `json:"renewal_date"`
	Roi         *float64           `json:"roi"`
	Unavailable *HealthUnavailable `json:"unavailable"`
}

Renewal A client's renewal readiness, from its latest published figures. `health` and `unavailable` are never both set.

type RenewalList added in v0.2.0 

type RenewalList struct {
	// Data One page of items, at most `limit`, in the documented order.
	Data []Renewal `json:"data"`

	// HasMore Whether another page exists.
	HasMore    bool    `json:"has_more"`
	NextCursor *string `json:"next_cursor"`
}

RenewalList Clients with a renewal date, by renewal date, then name, then id.

type Report added in v0.2.0 

type Report struct {
	CalculationID string `json:"calculation_id"`

	// ClientName Free text, as the recipient sees it.
	ClientName string    `json:"client_name"`
	CreatedAt  time.Time `json:"created_at"`

	// Disclosures In the order the calculation's coverage produced them. At most 12: each kind appears at most once.
	Disclosures   []Disclosure `json:"disclosures"`
	FirstViewedAt *time.Time   `json:"first_viewed_at"`
	ID            string       `json:"id"`
	LastViewedAt  *time.Time   `json:"last_viewed_at"`

	// Note Free text, `""` when empty.
	Note       string     `json:"note"`
	RevokedAt  *time.Time `json:"revoked_at"`
	ShareToken *string    `json:"share_token"`
	SharedAt   *time.Time `json:"shared_at"`

	// WorkspaceName Free text, as the recipient sees it.
	WorkspaceName string `json:"workspace_name"`
}

Report A report: the editorial layer over a published calculation.

type ReportList added in v0.2.0 

type ReportList struct {
	// Data One page of items, at most `limit`, in the documented order.
	Data []ReportSummary `json:"data"`

	// HasMore Whether another page exists.
	HasMore    bool    `json:"has_more"`
	NextCursor *string `json:"next_cursor"`
}

ReportList A calculation's reports, newest first, then id.

type ReportPatch added in v0.2.0 

type ReportPatch struct {
	// ClientName Free text, 1 to 200 characters counted in Unicode code points, padding included. Not trimmed: the value is stored as sent. Blank after trimming white space is `required`, and longer than 200 characters is `too_long`.
	ClientName *string `json:"client_name,omitempty"`

	// Disclosures Replaces the editorial state of every finding. It must name each stored finding exactly once: a missing one is `required`, an unknown one `invalid_value`, a repeated one `duplicate`. At most 50: a longer array is refused at its 51st element with one `too_many` at `/disclosures`.
	Disclosures *[]DisclosureEdit `json:"disclosures,omitempty"`
	Note        Nullable[string]  `json:"note,omitzero"`

	// WorkspaceName Free text, 1 to 200 characters counted in Unicode code points, padding included. Not trimmed: the value is stored as sent. Blank after trimming white space is `required`, and longer than 200 characters is `too_long`.
	WorkspaceName *string `json:"workspace_name,omitempty"`
}

ReportPatch A JSON Merge Patch (RFC 7396). An array replaces the stored array whole. A shared report is refused with `report_shared`.

type ReportSummary added in v0.2.0 

type ReportSummary struct {
	CalculationID string `json:"calculation_id"`

	// ClientName Free text, as the recipient sees it.
	ClientName    string     `json:"client_name"`
	CreatedAt     time.Time  `json:"created_at"`
	FirstViewedAt *time.Time `json:"first_viewed_at"`
	ID            string     `json:"id"`
	LastViewedAt  *time.Time `json:"last_viewed_at"`

	// Note Free text, `""` when empty.
	Note       string     `json:"note"`
	RevokedAt  *time.Time `json:"revoked_at"`
	ShareToken *string    `json:"share_token"`
	SharedAt   *time.Time `json:"shared_at"`

	// WorkspaceName Free text, as the recipient sees it.
	WorkspaceName string `json:"workspace_name"`
}

ReportSummary A report as the list returns it: without `disclosures`. Read the report for its findings.

type ReportWithPreview added in v0.2.0 

type ReportWithPreview struct {
	CalculationID string `json:"calculation_id"`

	// ClientName Free text, as the recipient sees it.
	ClientName string    `json:"client_name"`
	CreatedAt  time.Time `json:"created_at"`

	// Disclosures In the order the calculation's coverage produced them. At most 12: each kind appears at most once.
	Disclosures   []Disclosure `json:"disclosures"`
	FirstViewedAt *time.Time   `json:"first_viewed_at"`
	ID            string       `json:"id"`
	LastViewedAt  *time.Time   `json:"last_viewed_at"`

	// Note Free text, `""` when empty.
	Note       string        `json:"note"`
	Preview    *PublicReport `json:"preview"`
	RevokedAt  *time.Time    `json:"revoked_at"`
	ShareToken *string       `json:"share_token"`
	SharedAt   *time.Time    `json:"shared_at"`

	// WorkspaceName Free text, as the recipient sees it.
	WorkspaceName string `json:"workspace_name"`
}

ReportWithPreview A report with its recipient preview, as the single read returns it.

type ReportsService added in v0.2.0 

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

ReportsService groups the operations on reports. Reach it as client.Reports.

func (*ReportsService) CreateForCalculation added in v0.2.0 

func (s *ReportsService) CreateForCalculation(ctx context.Context, calculationID string, opts ...IdempotentRequestOption) (*Report, error)

CreateForCalculation composes a report on a published calculation, with its disclosures taken from the calculation's coverage. It sends no request body.

Every attempt of the call sends one Idempotency-Key, so a retry cannot create a second report.

Needs the write scope. Operation createReport.

func (*ReportsService) Delete added in v0.2.0 

func (s *ReportsService) Delete(ctx context.Context, id string, opts ...RequestOption) error

Delete deletes an unshared report. A shared report cannot be deleted until a signed-in user revokes its link, which this SDK does not offer.

A retry after a lost response can answer 404 for a delete that succeeded.

Needs the write scope. Operation deleteReport.

func (ReportsService) Format added in v0.2.0 

func (s ReportsService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*ReportsService) Get added in v0.2.0 

func (s *ReportsService) Get(ctx context.Context, id string, opts ...RequestOption) (*ReportWithPreview, error)

Get reads a report.

Needs the read scope. Operation getReport.

func (*ReportsService) ListForCalculation added in v0.2.0 

func (s *ReportsService) ListForCalculation(ctx context.Context, calculationID string, query *ListCalculationReportsParams, opts ...RequestOption) (*Page[ReportSummary, ReportList], error)

ListForCalculation lists a calculation's reports, and returns the first page. Walk every report of every page with Page.All. A nil query sends none. Each item is a ReportSummary, without disclosures; ReportsService.Get reads a report with them.

Needs the read scope. Operation listCalculationReports.

func (*ReportsService) Update added in v0.2.0 

func (s *ReportsService) Update(ctx context.Context, id string, patch ReportPatch, opts ...RequestOption) (*Report, error)

Update edits a report with a merge patch: a member left out keeps its value, a Null clears it, and any other value sets it. A slice, such as Disclosures, replaces the stored one whole.

Never retried.

Needs the write scope. Operation updateReport.

type RequestOption added in v0.2.0 

type RequestOption interface {
	IdempotentRequestOption
	// contains filtered or unexported methods
}

RequestOption configures one call of any operation. Pass it as a method's last argument; it applies to that call alone.

func WithRequestHeader added in v0.2.0 

func WithRequestHeader(name, value string) RequestOption

WithRequestHeader sends one header on every attempt of this call. It replaces a header of the same name, in any case, from the client's WithHeader or from the SDK, such as User-Agent, so one header is sent.

It may not name Authorization, Content-Type, Idempotency-Key or X-Request-Id, which the SDK sets, nor Host, Content-Length or Transfer-Encoding, which net/http sets. That, a name that is not an HTTP token, or a value holding a control character such as a line feed, is refused before anything is sent, with an error that does not match ErrAllisall.

func WithRequestMaxRetries added in v0.2.0 

func WithRequestMaxRetries(n int) RequestOption

WithRequestMaxRetries sets how many times this call is retried, in place of the client's WithMaxRetries. It cannot make a request eligible that the SDK never retries, such as a PATCH. A negative number is refused, before anything is sent, with an error matching ErrAllisall.

func WithRequestTimeout added in v0.2.0 

func WithRequestTimeout(d time.Duration) RequestOption

WithRequestTimeout bounds each attempt of this call, in place of the client's WithTimeout. Bound the whole call with its context. A duration of zero or less is refused, before anything is sent, with an error matching ErrAllisall.

type RoiResult added in v0.2.0 

type RoiResult struct {
	ClientID string `json:"client_id"`

	// Cost A cost computation.
	Cost       CostResult `json:"cost"`
	Currency   string     `json:"currency"`
	MinorUnits int        `json:"minor_units"`

	// Period A half-open range of instants, `[from, to)`. An unbounded side is `null`.
	Period Period `json:"period"`

	// Ratios The two return ratios. Both are `null` together, exactly when `undefined_reason` is set.
	Ratios Ratios `json:"ratios"`

	// Value A value computation.
	Value ValueResult `json:"value"`
}

RoiResult A client's ROI over a period: value and cost, composed and divided.

type TokenCostLine added in v0.2.0 

type TokenCostLine struct {
	Events int `json:"events"`

	// InRate The price of 1,000 input tokens used.
	InRate Decimal `json:"in_rate"`
	Model  string  `json:"model"`

	// OutRate The price of 1,000 output tokens used.
	OutRate   Decimal `json:"out_rate"`
	TokensIn  int     `json:"tokens_in"`
	TokensOut int     `json:"tokens_out"`
	Total     Decimal `json:"total"`
}

TokenCostLine Model events valued from their tokens at the price table.

type UnattributedLineItem added in v0.2.0 

type UnattributedLineItem struct {
	AgentID   string `json:"agent_id"`
	AgentName string `json:"agent_name"`
	ID        string `json:"id"`
	Label     string `json:"label"`
}

UnattributedLineItem An agent-targeted line item that reaches no client.

type UndefinedReason added in v0.2.0 

type UndefinedReason string

UndefinedReason Why the ratios are `null`. `no_value_model`: the client has no active value model. `zero_cost`: operating cost is zero or negative, so neither ratio has a denominator. `no_counted_clients` (dashboard only): no client is counted in the month's totals. 

const (
	UndefinedReasonNoCountedClients UndefinedReason = "no_counted_clients"
	UndefinedReasonNoValueModel     UndefinedReason = "no_value_model"
	UndefinedReasonZeroCost         UndefinedReason = "zero_cost"
)

Defines values for UndefinedReason.

func (UndefinedReason) Valid added in v0.2.0 

func (e UndefinedReason) Valid() bool

Valid indicates whether the value is a known member of the UndefinedReason enum.

type ValueCoverage added in v0.2.0 

type ValueCoverage struct {
	// ClientKeyUnset Whether the client has no `client_key`, so only solo-agent attribution reaches it.
	ClientKeyUnset bool `json:"client_key_unset"`

	// LineItemsEmpty Whether the active model has no line items.
	LineItemsEmpty bool `json:"line_items_empty"`

	// PeriodPrecedesModel Whether the period holds events from before the model was created.
	PeriodPrecedesModel bool `json:"period_precedes_model"`

	// UnattributableOutcomeEvents Outcome events in the workspace that attribute to no client.
	UnattributableOutcomeEvents int `json:"unattributable_outcome_events"`

	// UnmatchedClientKeys Event client keys that match no client in the workspace, by event count, largest first, then by client key compared by Unicode code point. At most 100: `unmatched_client_keys_omitted` counts the rest.
	UnmatchedClientKeys []struct {
		ClientKey string `json:"client_key"`
		Events    int    `json:"events"`
	} `json:"unmatched_client_keys"`

	// UnmatchedClientKeysOmitted How many unmatched client keys `unmatched_client_keys` leaves out, `0` when it lists every one.
	UnmatchedClientKeysOmitted int `json:"unmatched_client_keys_omitted"`

	// UnpricedOutcomeTypes Outcome types attributed to the client that no line item prices, by quantity, largest first, then by outcome type compared by Unicode code point. At most 100: `unpriced_outcome_types_omitted` counts the rest.
	UnpricedOutcomeTypes []OutcomeTypeUsage `json:"unpriced_outcome_types"`

	// UnpricedOutcomeTypesOmitted How many unpriced outcome types `unpriced_outcome_types` leaves out, `0` when it lists every one. The totals and counts in the response cover every one.
	UnpricedOutcomeTypesOmitted int `json:"unpriced_outcome_types_omitted"`
}

ValueCoverage Every way value could be missing from the total.

type ValueLine added in v0.2.0 

type ValueLine struct {
	Events         int     `json:"events"`
	Label          string  `json:"label"`
	OutcomeType    string  `json:"outcome_type"`
	ProvenanceNote string  `json:"provenance_note"`
	Quantity       float64 `json:"quantity"`
	Total          Decimal `json:"total"`
	UnitValue      Decimal `json:"unit_value"`
}

ValueLine One priced outcome type in a value computation.

type ValueLineItem added in v0.2.0 

type ValueLineItem struct {
	ID string `json:"id"`

	// Label Free text.
	Label string `json:"label"`

	// OutcomeType The outcome type this line prices. Matched against events case-insensitively, after trimming.
	OutcomeType string `json:"outcome_type"`

	// Position Display order, from 0.
	Position int `json:"position"`

	// ProvenanceNote How the unit value was agreed. Free text, `""` when empty.
	ProvenanceNote string `json:"provenance_note"`

	// UnitValue The value of one unit of the outcome, at most 4 decimal places.
	UnitValue Decimal `json:"unit_value"`
}

ValueLineItem One outcome type priced by a value model.

type ValueLineItemInput added in v0.2.0 

type ValueLineItemInput struct {
	// Label Free text, trimmed of white space (the Unicode `White_Space` property) at both ends. The trimmed label is stored. It holds 1 to 200 characters, counted in Unicode code points after trimming: blank after trimming is `required`, and longer than 200 characters after trimming is `too_long`. U+0000 is `invalid_format`, as in every request string. No JSON Schema keyword measures a length after trimming, so the schema states no `maxLength`; a `maxLength` of 200 would refuse a padded label the server accepts.
	Label string `json:"label"`

	// OutcomeType 1 to 200 characters, counted as sent. Not trimmed: a value with white space (the Unicode `White_Space` property) at either end, or white space only, is refused with `invalid_format`. Unique within the set, case-insensitively.
	OutcomeType    string  `json:"outcome_type"`
	ProvenanceNote *string `json:"provenance_note,omitempty"`

	// UnitValue At least 0 and below 100,000,000, with at most 4 decimal places; more is refused with `too_precise`, never rounded. Absent means 0, because templates ship every unit value as 0 on purpose.
	UnitValue *Decimal `json:"unit_value,omitempty"`
}

ValueLineItemInput defines model for ValueLineItemInput.

type ValueLineItemsSet added in v0.2.0 

type ValueLineItemsSet struct {
	// LineItems The complete set, at most 50. `[]` empties it. Stored `position` follows this order.
	LineItems []ValueLineItemInput `json:"line_items"`

	// Version The `version` of the model the caller read. A different stored version is refused with `value_model_version_stale`. A value of 0 or less is `out_of_range`; an absent or `null` one is `required`.
	Version int `json:"version"`
}

ValueLineItemsSet defines model for ValueLineItemsSet.

type ValueModel added in v0.2.0 

type ValueModel struct {
	ClientID  string    `json:"client_id"`
	CreatedAt time.Time `json:"created_at"`
	Currency  string    `json:"currency"`
	ID        string    `json:"id"`

	// LineItems At most 50, ordered by `position`.
	LineItems []ValueLineItem `json:"line_items"`

	// Name Free text.
	Name string `json:"name"`

	// Status A value model's status. At most one model per client is `active`.
	Status    ValueModelStatus `json:"status"`
	UpdatedAt time.Time        `json:"updated_at"`

	// Version The optimistic-concurrency version. Replacing the line items requires the current value.
	Version int `json:"version"`
}

ValueModel A value model: how one client's outcomes are priced.

type ValueModelCreate added in v0.2.0 

type ValueModelCreate struct {
	CopyFromModelID *string `json:"copy_from_model_id,omitempty"`

	// Name Free text, trimmed of white space (the Unicode `White_Space` property) at both ends. The trimmed name is stored. It holds 1 to 200 characters, counted in Unicode code points after trimming: blank after trimming is `required`, and longer than 200 characters after trimming is `too_long`. U+0000 is `invalid_format`, as in every request string. No JSON Schema keyword measures a length after trimming, so the schema states no `maxLength`; a `maxLength` of 200 would refuse a padded name the server accepts.
	Name       string  `json:"name"`
	TemplateID *string `json:"template_id,omitempty"`
}

ValueModelCreate Creates the client's active model. `template_id` and `copy_from_model_id` are create-only and are not echoed. Setting both is refused with `mutually_exclusive` at `/copy_from_model_id`. With neither, the model starts with no line items.

type ValueModelList added in v0.2.0 

type ValueModelList struct {
	// Data One page of items, at most `limit`, in the documented order.
	Data []ValueModelSummary `json:"data"`

	// HasMore Whether another page exists.
	HasMore    bool    `json:"has_more"`
	NextCursor *string `json:"next_cursor"`
}

ValueModelList Value models: active first, then newest first, then id.

type ValueModelPatch added in v0.2.0 

type ValueModelPatch struct {
	// Name Free text, trimmed of white space (the Unicode `White_Space` property) at both ends. The trimmed name is stored. It holds 1 to 200 characters, counted in Unicode code points after trimming: blank after trimming is `required`, and longer than 200 characters after trimming is `too_long`. U+0000 is `invalid_format`, as in every request string. No JSON Schema keyword measures a length after trimming, so the schema states no `maxLength`; a `maxLength` of 200 would refuse a padded name the server accepts.
	Name *string `json:"name,omitempty"`

	// Status A value model's status. At most one model per client is `active`.
	Status *ValueModelStatus `json:"status,omitempty"`
}

ValueModelPatch A JSON Merge Patch (RFC 7396) of the client's active model. Setting `status` to `archived` frees the client for a new active model.

type ValueModelRef added in v0.2.0 

type ValueModelRef struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Version int    `json:"version"`
}

ValueModelRef The value model a figure was computed with.

type ValueModelStatus added in v0.2.0 

type ValueModelStatus string

ValueModelStatus A value model's status. At most one model per client is `active`. 

const (
	ValueModelStatusActive   ValueModelStatus = "active"
	ValueModelStatusArchived ValueModelStatus = "archived"
)

Defines values for ValueModelStatus.

func (ValueModelStatus) Valid added in v0.2.0 

func (e ValueModelStatus) Valid() bool

Valid indicates whether the value is a known member of the ValueModelStatus enum.

type ValueModelSummary added in v0.2.0 

type ValueModelSummary struct {
	ClientID   string    `json:"client_id"`
	ClientName string    `json:"client_name"`
	CreatedAt  time.Time `json:"created_at"`
	ID         string    `json:"id"`

	// LineItems How many line items the model has.
	LineItems int    `json:"line_items"`
	Name      string `json:"name"`

	// Status A value model's status. At most one model per client is `active`.
	Status    ValueModelStatus `json:"status"`
	UpdatedAt time.Time        `json:"updated_at"`
	Version   int              `json:"version"`
}

ValueModelSummary A value model as the list returns it.

type ValueModelsService added in v0.2.0 

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

ValueModelsService groups the operations on value models and value templates. Reach it as client.ValueModels.

A method whose name ends in ForClient takes a client's id, and acts on that client's active value model; ValueModelsService.Get takes a value model's own id.

func (*ValueModelsService) CreateForClient added in v0.2.0 

func (s *ValueModelsService) CreateForClient(ctx context.Context, clientID string, body ValueModelCreate, opts ...IdempotentRequestOption) (*ValueModel, error)

CreateForClient creates a client's value model.

Every attempt of the call sends one Idempotency-Key, so a retry cannot create a second value model.

Needs the write scope. Operation createValueModel.

func (*ValueModelsService) DeleteForClient added in v0.2.0 

func (s *ValueModelsService) DeleteForClient(ctx context.Context, clientID string, opts ...RequestOption) error

DeleteForClient deletes a client's active value model.

A retry after a lost response can answer 404 for a delete that succeeded.

Needs the write scope. Operation deleteValueModel.

func (ValueModelsService) Format added in v0.2.0 

func (s ValueModelsService) Format(f fmt.State, _ rune)

Format prints the service for every fmt verb without the client it belongs to, which holds the credential.

func (*ValueModelsService) Get added in v0.2.0 

func (s *ValueModelsService) Get(ctx context.Context, id string, opts ...RequestOption) (*ValueModel, error)

Get reads a value model by its own id, not its client's: any model in the workspace, archived ones included.

Needs the read scope. Operation getValueModel.

func (*ValueModelsService) GetForClient added in v0.2.0 

func (s *ValueModelsService) GetForClient(ctx context.Context, clientID string, opts ...RequestOption) (*ValueModel, error)

GetForClient reads a client's active value model.

Needs the read scope. Operation getClientValueModel.

func (*ValueModelsService) List added in v0.2.0 

func (s *ValueModelsService) List(ctx context.Context, query *ListValueModelsParams, opts ...RequestOption) (*Page[ValueModelSummary, ValueModelList], error)

List lists value models, and returns the first page. Walk every value model of every page with Page.All. A nil query sends none.

Needs the read scope. Operation listValueModels.

func (*ValueModelsService) ListTemplates added in v0.2.0 

func (s *ValueModelsService) ListTemplates(ctx context.Context, query *ListValueTemplatesParams, opts ...RequestOption) (*Page[ValueTemplate, ValueTemplateList], error)

ListTemplates lists value templates, and returns the first page. Walk every template of every page with Page.All. A nil query sends none.

Needs the read scope. Operation listValueTemplates.

func (*ValueModelsService) SetLineItemsForClient added in v0.2.0 

func (s *ValueModelsService) SetLineItemsForClient(ctx context.Context, clientID string, body ValueLineItemsSet, opts ...RequestOption) (*ValueModel, error)

SetLineItemsForClient replaces the line items of a client's active value model, as a whole set. It is guarded by body.Version: a stale version is refused rather than overwriting a co-editor's change. Read the current version with ValueModelsService.GetForClient.

Never retried: a repeat of a write that landed would be refused as stale. After a network error the write may or may not have landed, so re-read the value model's Version with ValueModelsService.GetForClient before trying again.

Needs the write scope. Operation setValueModelLineItems.

func (*ValueModelsService) UpdateForClient added in v0.2.0 

func (s *ValueModelsService) UpdateForClient(ctx context.Context, clientID string, patch ValueModelPatch, opts ...RequestOption) (*ValueModel, error)

UpdateForClient updates a client's active value model with a merge patch: a member left out keeps its value, and any other value sets it.

Never retried.

Needs the write scope. Operation updateValueModel.

type ValueResult added in v0.2.0 

type ValueResult struct {
	// Coverage Every way value could be missing from the total.
	Coverage ValueCoverage `json:"coverage"`

	// Lines One line for each line item of the model, in line-item order, so at most 50. An outcome type no line item prices is never a line; it is listed in `coverage.unpriced_outcome_types`.
	Lines      []ValueLine    `json:"lines"`
	Total      *Decimal       `json:"total"`
	ValueModel *ValueModelRef `json:"value_model"`
}

ValueResult A value computation.

type ValueTemplate added in v0.2.0 

type ValueTemplate struct {
	Description string `json:"description"`

	// ID A stable slug.
	//
	// Examples: support-automation
	ID string `json:"id"`

	// LineItems In display order.
	LineItems []ValueTemplateLineItem `json:"line_items"`
	Name      string                  `json:"name"`
}

ValueTemplate A built-in starting point for a value model.

type ValueTemplateLineItem added in v0.2.0 

type ValueTemplateLineItem struct {
	Label          string `json:"label"`
	OutcomeType    string `json:"outcome_type"`
	ProvenanceNote string `json:"provenance_note"`

	// UnitValue Always 0: a template supplies structure, never a number.
	UnitValue Decimal `json:"unit_value"`
}

ValueTemplateLineItem defines model for ValueTemplateLineItem.

type ValueTemplateList added in v0.2.0 

type ValueTemplateList struct {
	// Data One page of items, at most `limit`, in the documented order.
	Data []ValueTemplate `json:"data"`

	// HasMore Whether another page exists.
	HasMore    bool    `json:"has_more"`
	NextCursor *string `json:"next_cursor"`
}

ValueTemplateList Templates in display order.

Source Files

View all Source files

Directories

Path Synopsis
examples
commit_import command
Command commit_import imports a CSV file of events and prints the outcome.
 Command commit_import imports a CSV file of events and prints the outcome.
create_agent command
Command create_agent creates an agent and prints its id.
 Command create_agent creates an agent and prints its id.
create_calculation command
Command create_calculation freezes a client's ROI for August 2026 as a draft calculation.
 Command create_calculation freezes a client's ROI for August 2026 as a draft calculation.
create_client command
Command create_client creates a client and prints its id.
 Command create_client creates a client and prints its id.
create_cost_line_item command
Command create_cost_line_item creates a monthly cost line item for a client.
 Command create_cost_line_item creates a monthly cost line item for a client.
create_report command
Command create_report composes a report on a published calculation.
 Command create_report composes a report on a published calculation.
create_value_model command
Command create_value_model creates a client's value model from a template.
 Command create_value_model creates a client's value model from a template.
delete_agent command
Command delete_agent deletes an agent.
 Command delete_agent deletes an agent.
delete_calculation command
Command delete_calculation deletes a draft calculation.
 Command delete_calculation deletes a draft calculation.
delete_client command
Command delete_client deletes a client.
 Command delete_client deletes a client.
delete_cost_line_item command
Command delete_cost_line_item deletes a cost line item.
 Command delete_cost_line_item deletes a cost line item.
delete_report command
Command delete_report deletes a report that was never shared.
 Command delete_report deletes a report that was never shared.
delete_value_model command
Command delete_value_model deletes a client's value model.
 Command delete_value_model deletes a client's value model.
get_agent command
Command get_agent reads an agent and prints its statistics.
 Command get_agent reads an agent and prints its statistics.
get_calculation command
Command get_calculation reads a calculation and prints its figures.
 Command get_calculation reads a calculation and prints its figures.
get_client command
Command get_client reads a client and prints its assigned agents.
 Command get_client reads a client and prints its assigned agents.
get_client_anomalies command
Command get_client_anomalies prints what looks unusual in a client's events in August 2026.
 Command get_client_anomalies prints what looks unusual in a client's events in August 2026.
get_client_cost command
Command get_client_cost prints what serving a client cost in August 2026.
 Command get_client_cost prints what serving a client cost in August 2026.
get_client_roi command
Command get_client_roi prints a client's return on investment for August 2026.
 Command get_client_roi prints a client's return on investment for August 2026.
get_client_value command
Command get_client_value prints the value a client's outcomes produced in August 2026.
 Command get_client_value prints the value a client's outcomes produced in August 2026.
get_client_value_model command
Command get_client_value_model reads a client's value model and prints its line items.
 Command get_client_value_model reads a client's value model and prints its line items.
get_cost_line_item command
Command get_cost_line_item reads a cost line item.
 Command get_cost_line_item reads a cost line item.
get_dashboard command
Command get_dashboard prints the workspace's published figures for August 2026.
 Command get_dashboard prints the workspace's published figures for August 2026.
get_health command
Command get_health checks that the allisall API is up and prints its version.
 Command get_health checks that the allisall API is up and prints its version.
get_price_table command
Command get_price_table prints the price table's rate for each model.
 Command get_price_table prints the price table's rate for each model.
get_report command
Command get_report reads a report and prints its disclosures.
 Command get_report reads a report and prints its disclosures.
get_value_model command
Command get_value_model reads a value model and prints its line items.
 Command get_value_model reads a value model and prints its line items.
ingest command
Command ingest sends one event to the allisall API and prints the outcome.
 Command ingest sends one event to the allisall API and prints the outcome.
list_agents command
Command list_agents prints every agent in the workspace.
 Command list_agents prints every agent in the workspace.
list_calculation_reports command
Command list_calculation_reports prints every report of a calculation.
 Command list_calculation_reports prints every report of a calculation.
list_client_calculations command
Command list_client_calculations prints every calculation of a client.
 Command list_client_calculations prints every calculation of a client.
list_client_events command
Command list_client_events prints every event attributed to a client in August 2026.
 Command list_client_events prints every event attributed to a client in August 2026.
list_client_outcome_types command
Command list_client_outcome_types prints every outcome type a client's events carry.
 Command list_client_outcome_types prints every outcome type a client's events carry.
list_clients command
Command list_clients prints every client in the workspace.
 Command list_clients prints every client in the workspace.
list_cost_line_items command
Command list_cost_line_items prints every cost line item in the workspace.
 Command list_cost_line_items prints every cost line item in the workspace.
list_outcome_types command
Command list_outcome_types prints every outcome type the workspace's events carry.
 Command list_outcome_types prints every outcome type the workspace's events carry.
list_renewals command
Command list_renewals prints every client with a renewal date, and its latest ROI.
 Command list_renewals prints every client with a renewal date, and its latest ROI.
list_value_models command
Command list_value_models prints every value model in the workspace.
 Command list_value_models prints every value model in the workspace.
list_value_templates command
Command list_value_templates prints every value template.
 Command list_value_templates prints every value template.
preview_import command
Command preview_import previews a CSV import and prints what it would store, without storing anything.
 Command preview_import previews a CSV import and prints what it would store, without storing anything.
set_client_agents command
Command set_client_agents assigns an agent to a client.
 Command set_client_agents assigns an agent to a client.
set_price_table command
Command set_price_table replaces the price table.
 Command set_price_table replaces the price table.
set_value_model_line_items command
Command set_value_model_line_items replaces the line items of a client's value model.
 Command set_value_model_line_items replaces the line items of a client's value model.
update_agent command
Command update_agent retires an agent.
 Command update_agent retires an agent.
update_client command
Command update_client marks a client as churned.
 Command update_client marks a client as churned.
update_cost_line_item command
Command update_cost_line_item sets the end date of a cost line item.
 Command update_cost_line_item sets the end date of a cost line item.
update_report command
Command update_report edits a report's note and disclosures.
 Command update_report edits a report's note and disclosures.
update_value_model command
Command update_value_model archives a client's value model.
 Command update_value_model archives a client's value model.

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.