seatlayer

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2026 License: MIT Imports: 18 Imported by: 0

README

SeatLayer Go SDK

CI Go Reference

Official Go server SDK for the SeatLayer reserved-seating API.

Server-side only. This package authenticates with your secret key. Never embed it in anything a ticket buyer can reach — browser surfaces get short-lived, origin-bound tokens that you mint here.

Install

go get github.com/seatlayer/seatlayer-go

Requires Go 1.23 or newer (for range-over-func iterators). No dependencies — standard library only.

Quick start

import (
    "context"
    "os"

    "github.com/seatlayer/seatlayer-go"
)

client, err := seatlayer.New(os.Getenv("SEATLAYER_SECRET_KEY"))
if err != nil {
    return err
}
ctx := context.Background()

// 1. Provision a venue for a new organiser from one of your templates.
chart, err := client.Charts.Copy(ctx, "c_template_arena")
if err != nil {
    return err
}
chartID := chart["meta"].(map[string]any)["id"].(string)
if _, err := client.Charts.Publish(ctx, chartID); err != nil {
    return err
}

// 2. Create an event on it.
event, err := client.Events.Create(ctx, seatlayer.EventCreateParams{
    ChartID: chartID,
    Name:    "Spring Gala",
})
if err != nil {
    return err
}
eventKey := event["meta"].(map[string]any)["key"].(string)

// 3. Sell four seats over the phone.
held, err := client.Inventory.HoldBestAvailable(ctx, eventKey, seatlayer.BestAvailableParams{Qty: 4})
if err != nil {
    return err
}
// … take payment against held["items"], which carry authoritative prices …
_, err = client.Inventory.Book(ctx, eventKey, seatlayer.BookParams{
    HoldID:     held["holdId"].(string),
    BookingRef: "order-8842",
})

For nullable event-create fields, ordinary scalar fields cover the common value-or-omit case. Use the Nullable overlay when the wire call must contain an explicit JSON null, for example Nullable: seatlayer.EventCreateNullableFields{Venue: seatlayer.FieldNull[string]()}.

Every method takes a context.Context. Cancelling it stops retries immediately rather than being treated as a transient fault to back off through.

Test vs live

Keys carry their own mode. sk_test_… keys can only touch test-mode events and sk_live_… only live ones; crossing them returns 403 mode_mismatch.

client, err := seatlayer.New(os.Getenv("SEATLAYER_SECRET_KEY"))
if err != nil {
    return err
}
if os.Getenv("ENV") == "production" && client.Mode() != "live" {
    return errors.New("refusing to boot production against test-mode seating data")
}

A publishable pk_ key is rejected by New with a message naming the mistake, rather than failing as a 401 three round-trips later.

The two selling flows

Buyer picks seats in the browser. Your frontend holds them; your backend confirms the price and books. Never price from what the browser sent you — RetrieveHold is authoritative.

hold, err := client.Inventory.RetrieveHold(ctx, eventKey, holdID)
// … charge from hold.Items, whose UnitPrice and Currency are authoritative …
_, err = client.Inventory.Book(ctx, eventKey, seatlayer.BookParams{
    HoldID: holdID, BookingRef: charge.ID,
})

Your backend picks the seats. Phone orders, box office, comps.

// Payment already taken — book outright, so nothing is stranded if a second call fails.
_, err := client.Inventory.BookBestAvailable(ctx, eventKey, seatlayer.BestAvailableParams{
    Qty: 2, BookingRef: "phone-1183",
})

// Or name the seats yourself.
_, err = client.Inventory.BoxOfficeBook(ctx, eventKey, []string{"A-1", "A-2"}, "comp-14")

Private and partner sales

Channels reserve inventory for a partner, member group, presale, or other private allocation. A buyer access session is short-lived and origin-bound, so the browser receives only the allocation it is allowed to sell; your secret key remains on your server.

_, err := client.Channels.CreateChannel(ctx, eventKey, seatlayer.ChannelCreateParams{
	Name:         "Venue members",
	AccessIntent: "private",
})

_, err = client.Channels.UpdateAssignments(ctx, eventKey, seatlayer.ChannelAssignmentParams{
	Labels:            []string{"A-1", "A-2"},
	AssignmentVersion: 1,
	TargetChannelID:   "ch_members",
})

access, err := client.Channels.CreateBuyerAccessSession(ctx, eventKey,
	seatlayer.BuyerAccessSessionParams{
		ChannelIDs:    []string{"ch_members"},
		IncludePublic: false,
		AllowedOrigin: "https://members.example",
		MaxQuantity:   2,
	})

Pass the returned token to the buyer SDK. Trusted backend sale params accept ChannelIDs, an explicit privileged IgnoreChannelRestrictions flag, and an audit Reason.

Listing and pagination

List returns one Page plus a cursor. All is a range-over-func iterator that pages as you consume it — deliberately not a slice, because the point of paginating is to not hold an unbounded result set in memory.

// One page, your own paging.
page, err := client.Events.List(ctx, &seatlayer.EventListParams{Limit: 50})
page.Items
page.NextCursor   // "" once exhausted

// Or let the SDK walk it.
for event, err := range client.Events.All(ctx, nil) {
    if err != nil {
        return err
    }
    sync(event)
}

The error rides alongside each item so a failed page reaches you — an iterator that silently ended on error would look identical to a list that finished.

Listing events includes live availability counts by default, which costs the server one round-trip per event. All drops them automatically — walking a whole catalogue is exactly when you don't want that — and you can control it explicitly:

client.Events.List(ctx, &seatlayer.EventListParams{Limit: 50, NoCounts: true})

Keeping a hold alive

When an order takes longer than the checkout window — an invoice, a phone sale — extend rather than release and re-hold. Releasing first hands the seats to whoever is racing for them in between.

_, err := client.Inventory.ExtendHold(ctx, eventKey, holdID, 10*60*1000)

var conflict *seatlayer.ConflictError
if errors.As(err, &conflict) {
    // Gone, expired, or at its renewal cap — the buyer has to re-pick.
}

Embedding the control room

Your secret key never reaches a browser. Mint a scoped token instead.

session, err := client.Sessions.CreateManageSession(ctx, eventKey, seatlayer.ManageSessionParams{
    AllowedOrigin:    "https://box-office.yourplatform.com",
    Capabilities:     []seatlayer.ManageCapability{
        seatlayer.CapabilityView,
        seatlayer.CapabilityBlock,
    },
    ExpiresInSeconds: 3600,
})

Capabilities is required by this SDK even though the raw API safely defaults an omitted list to view-only (event:view). Keeping the field required makes browser authority visible at every call site. Grant the smallest set the page needs. The constants also cover channel management and SeatLayer-managed orders, refunds, ticket delivery, door, and box-office capabilities.

Designer minting returns a DesignerSessionEnvelope; the token and the effective safe-mode and feature policy live under result.Session. Pass SafeModeOptions only with Mode: "safe".

Webhooks

Webhook methods expose the wire envelopes directly: List returns WebhookList.Subs, Create returns WebhookCreateEnvelope with the show-once Secret, and Update returns WebhookEnvelope.Sub. Use the WebhookEvent… constants for the eight accepted event names and WebhookDeliveryListParams for limit, status, and before filters.

Verify every delivery against the raw body. Decoding and re-encoding changes the bytes — in Go specifically, encoding/json marshals map keys in sorted order while a real delivery arrives in the order we serialised it, so a round trip reorders it and verification fails.

func handleWebhook(w http.ResponseWriter, r *http.Request) {
    payload, err := io.ReadAll(r.Body)   // raw bytes, before any decoding
    if err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    event, err := seatlayer.VerifyWebhook(
        payload,
        r.Header.Get("X-SeatLayer-Signature"),
        os.Getenv("SEATLAYER_WEBHOOK_SECRET"),
    )
    if errors.Is(err, seatlayer.ErrWebhookVerification) {
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    // The signed body carries "at", but nothing enforces a freshness window, so a
    // captured delivery stays valid indefinitely. Deduplicate on occurrenceId —
    // this is your replay protection, not an optimisation.
    if alreadyProcessed(event["occurrenceId"].(string)) {
        w.WriteHeader(http.StatusOK)
        return
    }

    process(event)
    w.WriteHeader(http.StatusOK)
}

Errors

Errors are values here, not exceptions — reach for errors.As:

_, err := client.Inventory.HoldBestAvailable(ctx, eventKey, seatlayer.BestAvailableParams{Qty: 6})

var conflict *seatlayer.ConflictError
var rateLimit *seatlayer.RateLimitError
var auth *seatlayer.AuthError

switch {
case errors.As(err, &conflict) && conflict.SoldOut():
    return offerAlternativeDates()          // a business outcome, not a bug
case errors.As(err, &rateLimit):
    return retryAfter(rateLimit.RetryAfter)
case errors.As(err, &auth) && auth.ModeMismatch():
    return errors.New("test key pointed at a live event, or the reverse")
case err != nil:
    return err
}
Type Status Means
AuthError 401, 403 Bad, revoked, or wrong-mode key
NotFoundError 404 No such resource for this organisation
ConflictError 409 Inventory moved, or a guard rejected the change
ValidationError 422 Understood and rejected
RateLimitError 429 Over budget; carries RetryAfter
ConnectionError — No answer: DNS, TLS, socket, context deadline (unwraps)

Every API error carries Status, Code, Body, and RequestID — quote the request id in support requests.

Reliability

Retries. Reads (GET/HEAD) retry 429, 408 and 5xx with exponential backoff and full jitter; Retry-After wins when the server sends it. Automatic mutation retries are limited to the four operations backed by exact response replay: Charts.Create, Charts.Copy, Events.Create, and Workspaces.Create. Other 4xx responses are never retried.

Idempotency. Those four replay-backed operations carry an Idempotency-Key, generated when you do not supply one and reused across attempts. Other mutations are single-attempt and receive no automatic key. A caller-supplied key is forwarded but does not enable retries. This includes inventory holds and bookings, show-once credential or secret creation, unsupported operations, and raw Do mutations. Keep BookingRef in the booking body for reconciliation, but handle an unknown network outcome explicitly instead of automatically repeating the sale.

client.Events.Create(ctx, seatlayer.EventCreateParams{
    ChartID: chartID, IdempotencyKey: "provision-event-" + eventID,
})

client, err := seatlayer.New(
    os.Getenv("SEATLAYER_SECRET_KEY"),
    seatlayer.WithMaxRetries(3),
    seatlayer.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
)

Client is safe for concurrent use.

Escape hatch

For surface this SDK does not wrap yet, Do keeps auth and error mapping. Raw reads retain the read retry policy; raw mutations are always single-attempt because their replay contract is unknown:

client.Do(ctx, http.MethodPost, "/v1/events/ev_1/some-new-route", nil, map[string]any{"qty": 2}, "")

API surface

Service Methods
Charts List All Create Retrieve Update Delete Copy Archive Unarchive Publish
Events List All Create Retrieve Update Delete UpdatePoster DeletePoster UpdateChart Close Reopen Archive RetrieveHoldTTL UpdateHoldTTL RetrieveReport RetrieveLog
Channels ListChannels CreateChannel UpdateChannel UpdateAssignments ListAllocation RetrieveAccessPreview RetrieveReport Pause Unpause Archive CreateBuyerAccessSession ListBuyerAccessSessions RevokeBuyerAccessSession CreateAccessLink ListAccessLinks RotateAccessLink RevokeAccessLink
Inventory Hold HoldBestAvailable BookBestAvailable ExtendHold RetrieveHold Release Book BoxOfficeBook Unbook Block Unblock UnblockAll RetrieveAvailability UpdateAvailability ListBookings RetrieveBooking
Sessions CreateManageSession RevokeManageSession CreateDesignerSession RevokeDesignerSession
Webhooks List Create Update Delete ListDeliveries
Workspaces List Create Retrieve Update

Full reference: docs.seatlayer.io/server-sdk

Other SeatLayer SDKs
Surface Package
Browser (vanilla) @seatlayer/js
React @seatlayer/react
React Native @seatlayer/react-native
iOS seatlayer-ios
Android seatlayer-android
Flutter seatlayer
Node.js (server) @seatlayer/server
Python (server) seatlayer
PHP (server) seatlayer/seatlayer-php
Java (server) io.seatlayer:seatlayer-java
Go (server) github.com/seatlayer/seatlayer-go
Ruby (server) seatlayer
.NET (server) SeatLayer

Development

gofmt -l .          # must be empty
go vet ./...
go test -race ./...

License

MIT

Documentation

Overview

Package seatlayer is the official Go server SDK for the SeatLayer reserved-seating API.

Server-side only: this package authenticates with your secret key. Never embed it in anything a ticket buyer can reach — browser surfaces get short-lived, origin-bound tokens that you mint with Sessions. 

client, err := seatlayer.New(os.Getenv("SEATLAYER_SECRET_KEY"))
if err != nil {
	return err
}
held, err := client.Inventory.HoldBestAvailable(ctx, "summer-gala",
	seatlayer.BestAvailableParams{Qty: 4})

Index

Constants

View Source 
const (
	// DefaultBaseURL is the public API.
	DefaultBaseURL = "https://api.seatlayer.io"
	// DefaultMaxRetries counts total attempts, not extra ones.
	DefaultMaxRetries = 3
	// DefaultTimeout applies per attempt.
	DefaultTimeout = 30 * time.Second
)

Variables

View Source 
var ErrWebhookVerification = errors.New("seatlayer: webhook verification failed")

ErrWebhookVerification means the delivery did not come from SeatLayer. Respond 400 and do not process it.

Functions

func VerifyWebhook 

func VerifyWebhook(payload []byte, signature, secret string) (map[string]any, error)

VerifyWebhook checks a delivery's signature and returns its decoded payload.

payload must be the RAW request body — in net/http that is io.ReadAll(r.Body) before any decoding. Re-serialising a decoded body reorders keys and changes whitespace, so verification fails; the usual "fix" for that is to disable verification, which is why this takes bytes and does the work for you.

Errors wrap ErrWebhookVerification, so callers can test with errors.Is.

NOTE ON REPLAY: deliveries are signed over the body, which carries an "at" timestamp — but nothing enforces a freshness window, so a captured delivery stays valid indefinitely. Replay protection is yours: every event carries an occurrenceId, and the correct pattern is to record processed ids and ignore repeats. Do not skip this.

Types

type APIError 

type APIError struct {
	// Status is the HTTP status the API answered with.
	Status int
	// Code is the machine-readable slug: body "code", falling back to "error".
	Code string
	// Message is the human-readable message, when the API sent one.
	Message string
	// Body is the decoded error body, for fields this SDK does not model.
	Body map[string]any
	// RequestID comes from X-Request-ID. Quote it in support requests.
	RequestID string
}

APIError is the base error returned for any non-2xx response.

Go has no exception hierarchy, so the pattern here is errors.As against the specific types below rather than catch blocks. A sold-out seat is a business outcome that belongs in an if, not lumped in with a bad key: 

var conflict *ConflictError
if errors.As(err, &conflict) && conflict.SoldOut() {
	return offerAlternativeDates()
}

func (*APIError) Error 

func (e *APIError) Error() string
type AccessLink struct {
	ID                string           `json:"id"`
	ChannelID         string           `json:"channelId"`
	Label             *string          `json:"label"`
	IncludePublic     bool             `json:"includePublic"`
	ExpiresAt         int64            `json:"expiresAt"`
	MaxRedemptions    int              `json:"maxRedemptions"`
	Redemptions       int              `json:"redemptions"`
	MaxQuantity       int              `json:"maxQuantity"`
	SessionTTLSeconds int              `json:"sessionTtlSeconds"`
	State             AccessLinkState  `json:"state"`
	Status            AccessLinkStatus `json:"status"`
	CreatedAt         int64            `json:"createdAt"`
	CreatedBy         *string          `json:"createdBy"`
	RevokedAt         *int64           `json:"revokedAt"`
	LastRedeemedAt    *int64           `json:"lastRedeemedAt"`
	RotatedFrom       *string          `json:"rotatedFrom"`
	RotatedTo         *string          `json:"rotatedTo"`
}

AccessLink is the status projection. It never contains the one-time capability returned by create and rotate.

type AccessLinkCreateParams added in v0.3.0 

type AccessLinkCreateParams struct {
	Label             NullableField[string]
	ExpiresAt         int64
	MaxRedemptions    int
	MaxQuantity       int
	SessionTTLSeconds int
	IncludePublic     *bool
	Reason            string
	IdempotencyKey    string
}

AccessLinkCreateParams configures a hosted link. The response capability is revealed once and the operation is never automatically retried. 

type AccessLinkList struct {
	Links []AccessLinkListItem `json:"links"`
}

type AccessLinkListItem added in v0.3.0 

type AccessLinkListItem struct {
	AccessLink
	ActiveSessions int `json:"activeSessions"`
}

type AccessLinkReveal added in v0.3.0 

type AccessLinkReveal struct {
	Link          AccessLink  `json:"link"`
	URL           string      `json:"url"`
	Capability    string      `json:"capability"`
	RevealedOnce  bool        `json:"revealedOnce"`
	Previous      *AccessLink `json:"previous,omitempty"`
	EndedSessions *int        `json:"endedSessions,omitempty"`
}

AccessLinkReveal contains a capability that the API will never return again.

type AccessLinkRevokeParams added in v0.3.0 

type AccessLinkRevokeParams struct {
	EndActiveSessions bool
	Reason            string
}

AccessLinkRevokeParams controls optional session cascade and audit reason.

type AccessLinkRevokeResult added in v0.3.0 

type AccessLinkRevokeResult struct {
	OK            bool       `json:"ok"`
	Link          AccessLink `json:"link"`
	EndedSessions int        `json:"endedSessions"`
}

type AccessLinkRotateParams added in v0.3.0 

type AccessLinkRotateParams struct {
	EndActiveSessions bool
	Reason            string
}

AccessLinkRotateParams requires the caller to choose whether old sessions end.

type AccessLinkState added in v0.3.0 

type AccessLinkState string

AccessLinkState is the stored lifecycle state of a hosted link. 

const (
	AccessLinkActive  AccessLinkState = "active"
	AccessLinkRevoked AccessLinkState = "revoked"
	AccessLinkRotated AccessLinkState = "rotated"
)

type AccessLinkStatus added in v0.3.0 

type AccessLinkStatus string

AccessLinkStatus includes derived expiry and redemption-exhaustion states. 

const (
	AccessLinkStatusActive    AccessLinkStatus = "active"
	AccessLinkStatusRevoked   AccessLinkStatus = "revoked"
	AccessLinkStatusRotated   AccessLinkStatus = "rotated"
	AccessLinkStatusExpired   AccessLinkStatus = "expired"
	AccessLinkStatusExhausted AccessLinkStatus = "exhausted"
)

type AuthError 

type AuthError struct{ APIError }

AuthError is a 401 or 403 — bad key, revoked key, or a live key used against a test event.

func (*AuthError) ModeMismatch 

func (e *AuthError) ModeMismatch() bool

ModeMismatch reports whether the key's mode and the event's mode disagree. This is the most common cause of a "works locally, 403s in production" report.

type BestAvailableParams 

type BestAvailableParams struct {
	// Qty is clamped to the server maximum rather than rejected.
	Qty         int
	CategoryKey string
	ZoneID      string
	// TTLMs overrides the event's checkout window. Ignored by BookBestAvailable.
	TTLMs int64
	// BookingRef is required by BookBestAvailable and ignored by HoldBestAvailable.
	BookingRef     string
	IdempotencyKey string
	ChannelIDs     []string
	// IgnoreChannelRestrictions is a privileged backend override.
	IgnoreChannelRestrictions bool
	// Reason is written to the audit trail for channel use or an override.
	Reason string
}

BestAvailableParams asks us to choose the objects.

type BookParams 

type BookParams struct {
	// HoldID books a previously held selection…
	HoldID string
	// …or Labels books outright, with no prior hold.
	Labels         []string
	BookingRef     string
	IdempotencyKey string
	ChannelIDs     []string
	// IgnoreChannelRestrictions is a privileged backend override.
	IgnoreChannelRestrictions bool
	// Reason is written to the audit trail for channel use or an override.
	Reason string
}

BookParams books either a held selection or labels outright.

type BookingListParams added in v0.2.0 

type BookingListParams struct {
	Query  string
	State  string
	Limit  int
	Cursor string
}

BookingListParams filters and pages booking lifecycle records.

type BuyerAccessSessionListParams added in v0.2.0 

type BuyerAccessSessionListParams struct {
	Limit int
}

BuyerAccessSessionListParams limits the buyer access-session projection.

type BuyerAccessSessionNullableFields added in v0.3.0 

type BuyerAccessSessionNullableFields struct {
	MaxQuantity     NullableField[int]
	BuyerRef        NullableField[string]
	PartnerRef      NullableField[string]
	ClientRequestID NullableField[string]
}

BuyerAccessSessionNullableFields sends an explicit null for optional buyer metadata instead of silently applying the API default.

type BuyerAccessSessionParams added in v0.2.0 

type BuyerAccessSessionParams struct {
	ChannelIDs       []string
	IncludePublic    bool
	AllowedOrigin    string
	ExpiresInSeconds int
	MaxQuantity      int
	BuyerRef         string
	PartnerRef       string
	ClientRequestID  string
	IdempotencyKey   string
	// Nullable overrides fields when explicit JSON null is different from omission.
	Nullable BuyerAccessSessionNullableFields
}

BuyerAccessSessionParams defines the security boundary of a buyer token.

type ChannelArchiveParams added in v0.3.0 

type ChannelArchiveParams struct {
	Destination NullableField[string]
	Reason      string
}

ChannelArchiveParams permits the contract's explicit null destination.

type ChannelAssignmentParams added in v0.2.0 

type ChannelAssignmentParams struct {
	Labels            []string
	AssignmentVersion int64
	TargetChannelID   string
	Reason            string
	IdempotencyKey    string
}

ChannelAssignmentParams moves inventory between public and private allocation.

type ChannelCreateParams added in v0.2.0 

type ChannelCreateParams struct {
	Name           string
	Color          string
	Marker         string
	ExternalRef    string
	AccessIntent   string
	Reason         string
	IdempotencyKey string
}

ChannelCreateParams defines a private allocation channel.

type ChannelUpdateParams added in v0.2.0 

type ChannelUpdateParams struct {
	Name                  string
	AccessIntent          string
	AcknowledgeLiveAccess *bool
	Reason                string
}

ChannelUpdateParams defines mutable channel fields.

type ChannelsService added in v0.2.0 

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

ChannelsService manages private allocations, reporting, and buyer access.

func (*ChannelsService) Archive added in v0.2.0 

func (s *ChannelsService) Archive(
	ctx context.Context, eventKey, channelID string, p ChannelArchiveParams,
) (map[string]any, error)

Archive retires a channel with an explicit destination value. 

func (s *ChannelsService) CreateAccessLink(
	ctx context.Context, eventKey, channelID string, p AccessLinkCreateParams,
) (AccessLinkReveal, error)

CreateAccessLink mints a hosted link and its one-time capability.

func (*ChannelsService) CreateBuyerAccessSession added in v0.2.0 

func (s *ChannelsService) CreateBuyerAccessSession(
	ctx context.Context, eventKey string, p BuyerAccessSessionParams,
) (map[string]any, error)

CreateBuyerAccessSession mints a short-lived, origin-bound buyer token.

func (*ChannelsService) CreateChannel added in v0.2.0 

func (s *ChannelsService) CreateChannel(
	ctx context.Context, eventKey string, p ChannelCreateParams,
) (map[string]any, error)

CreateChannel creates a private allocation channel. 

func (s *ChannelsService) ListAccessLinks(
	ctx context.Context, eventKey, channelID string,
) (AccessLinkList, error)

ListAccessLinks returns status only, never a stored capability.

func (*ChannelsService) ListAllocation added in v0.2.0 

func (s *ChannelsService) ListAllocation(
	ctx context.Context, eventKey, afterLabel string, limit int,
) (map[string]any, error)

ListAllocation returns the current allocation ledger.

func (*ChannelsService) ListBuyerAccessSessions added in v0.2.0 

func (s *ChannelsService) ListBuyerAccessSessions(
	ctx context.Context, eventKey string, p BuyerAccessSessionListParams,
) (map[string]any, error)

ListBuyerAccessSessions returns one page of buyer access sessions.

func (*ChannelsService) ListChannels added in v0.2.0 

func (s *ChannelsService) ListChannels(
	ctx context.Context, eventKey string, includeArchived bool,
) (map[string]any, error)

ListChannels lists an event's allocation channels.

func (*ChannelsService) Pause added in v0.2.0 

func (s *ChannelsService) Pause(
	ctx context.Context, eventKey, channelID, reason string,
) (map[string]any, error)

Pause temporarily disables a channel.

func (*ChannelsService) RetrieveAccessPreview added in v0.2.0 

func (s *ChannelsService) RetrieveAccessPreview(
	ctx context.Context, eventKey string, channelIDs []string, includePublic *bool,
) (map[string]any, error)

RetrieveAccessPreview shows the inventory visible to a buyer access scope.

func (*ChannelsService) RetrieveReport added in v0.2.0 

func (s *ChannelsService) RetrieveReport(
	ctx context.Context, eventKey string,
) (map[string]any, error)

RetrieveReport returns channel allocation totals. 

func (s *ChannelsService) RevokeAccessLink(
	ctx context.Context, eventKey, channelID, linkID string,
	options ...AccessLinkRevokeParams,
) (AccessLinkRevokeResult, error)

RevokeAccessLink stops a hosted link from admitting new buyers.

func (*ChannelsService) RevokeBuyerAccessSession added in v0.2.0 

func (s *ChannelsService) RevokeBuyerAccessSession(
	ctx context.Context, eventKey, sessionID string,
) (map[string]any, error)

RevokeBuyerAccessSession revokes a buyer token before it expires. 

func (s *ChannelsService) RotateAccessLink(
	ctx context.Context, eventKey, channelID, linkID string, p AccessLinkRotateParams,
) (AccessLinkReveal, error)

RotateAccessLink replaces a hosted link and reveals the successor once.

func (*ChannelsService) Unpause added in v0.2.0 

func (s *ChannelsService) Unpause(
	ctx context.Context, eventKey, channelID, reason string,
) (map[string]any, error)

Unpause restores a paused channel.

func (*ChannelsService) UpdateAssignments added in v0.2.0 

func (s *ChannelsService) UpdateAssignments(
	ctx context.Context, eventKey string, p ChannelAssignmentParams,
) (map[string]any, error)

UpdateAssignments changes the allocation owner of inventory labels.

func (*ChannelsService) UpdateChannel added in v0.2.0 

func (s *ChannelsService) UpdateChannel(
	ctx context.Context, eventKey, channelID string, p ChannelUpdateParams,
) (map[string]any, error)

UpdateChannel updates a private allocation channel.

type ChartCopyParams added in v0.3.0 

type ChartCopyParams struct {
	Name           string
	ExternalRef    NullableField[string]
	WorkspaceID    string
	IdempotencyKey string
}

ChartCopyParams overrides fields inherited from the source chart.

type ChartCreateParams 

type ChartCreateParams struct {
	Name        string
	Doc         map[string]any
	ExternalRef string
	WorkspaceID string
	// IdempotencyKey makes a retried create collapse into the original.
	IdempotencyKey string
}

ChartCreateParams describes a new chart.

type ChartListParams 

type ChartListParams struct {
	WorkspaceID string
	ExternalRef string
	Archived    bool
	// Limit is the page size. Clamped server-side; asking for more is not an error.
	Limit int
	// Cursor continues a previous page. Leave empty to start.
	Cursor string
}

ChartListParams filters and pages a chart listing.

type ChartUpdateParams added in v0.3.0 

type ChartUpdateParams struct {
	Doc               map[string]any
	ExpectedUpdatedAt int64
	Name              string
	Issues            *float64
	ExternalRef       NullableField[string]
}

ChartUpdateParams supports both the optimistic document-replacement branch and the metadata-only branch of the chart update contract.

type ChartsService 

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

ChartsService covers seat-map definitions that events are created from.

Even when organisers draw their own venues in the embedded Designer you need this: CreateDesignerSession requires a chart id that already exists, so the usual platform flow is copy a template here, then hand over a session.

func (*ChartsService) All 

func (s *ChartsService) All(ctx context.Context, p *ChartListParams) iter.Seq2[map[string]any, error]

All walks every chart, paging transparently. 

for chart, err := range client.Charts.All(ctx, nil) { ... }

func (*ChartsService) Archive 

func (s *ChartsService) Archive(ctx context.Context, chartID string) (map[string]any, error)

Archive moves a chart to the archive.

func (*ChartsService) Copy 

func (s *ChartsService) Copy(
	ctx context.Context, chartID string, options ...ChartCopyParams,
) (map[string]any, error)

Copy duplicates a chart — the usual way to provision a venue from a template.

func (*ChartsService) Create 

func (s *ChartsService) Create(ctx context.Context, p ChartCreateParams) (map[string]any, error)

Create makes a chart. Pass Doc to import an existing document.

func (*ChartsService) Delete 

func (s *ChartsService) Delete(ctx context.Context, chartID string) error

Delete removes a chart.

func (*ChartsService) List 

func (s *ChartsService) List(ctx context.Context, p *ChartListParams) (Page, error)

List returns one page of charts.

func (*ChartsService) Publish 

func (s *ChartsService) Publish(ctx context.Context, chartID string) (map[string]any, error)

Publish publishes the draft. Events can only be created from a published chart.

func (*ChartsService) Retrieve 

func (s *ChartsService) Retrieve(ctx context.Context, chartID string) (map[string]any, error)

Retrieve fetches a chart and its document.

func (*ChartsService) Unarchive 

func (s *ChartsService) Unarchive(ctx context.Context, chartID string) (map[string]any, error)

Unarchive restores a chart from the archive.

func (*ChartsService) Update 

func (s *ChartsService) Update(
	ctx context.Context, chartID string, p ChartUpdateParams,
) (map[string]any, error)

Update changes a document and/or chart metadata. ExpectedUpdatedAt is required whenever Doc is supplied so concurrent writers cannot silently overwrite each other. ExternalRef can be FieldNull[string]() to clear it.

type Client 

type Client struct {
	Charts     *ChartsService
	Channels   *ChannelsService
	Events     *EventsService
	Inventory  *InventoryService
	Sessions   *SessionsService
	Webhooks   *WebhooksService
	Workspaces *WorkspacesService
	// contains filtered or unexported fields
}

Client talks to the SeatLayer server API.

It is safe for concurrent use: the underlying http.Client is, and Client holds no mutable state of its own.

func New 

func New(secretKey string, options ...Option) (*Client, error)

New builds a Client from a secret key.

It returns an error rather than panicking on a bad key, so a misconfigured deployment fails at startup with a message that names the problem.

func (*Client) Do 

func (c *Client) Do(
	ctx context.Context,
	method, path string,
	query url.Values,
	body any,
	idempotencyKey string,
) (map[string]any, error)

Do is the escape hatch for surface this SDK does not wrap yet. Reads retain retries; raw mutations are single-attempt because their replay contract is unknown.

func (*Client) Mode 

func (c *Client) Mode() string

Mode reports "live" or "test", derived from the key prefix.

func (*Client) Ready 

func (c *Client) Ready(ctx context.Context) (map[string]any, error)

Ready runs the dependency-aware readiness probe.

type ConflictError 

type ConflictError struct{ APIError }

ConflictError is a 409 — the seats moved under you.

Normal in ticketing, not exceptional: two buyers wanted the same seat and one lost.

func (*ConflictError) Conflicts 

func (e *ConflictError) Conflicts() []map[string]any

Conflicts returns the per-object conflicts, when the endpoint reports them.

func (*ConflictError) SoldOut 

func (e *ConflictError) SoldOut() bool

SoldOut reports whether best-available could not find enough free inventory.

type ConnectionError 

type ConnectionError struct {
	Op  string
	Err error
}

ConnectionError means the request never got an answer: DNS, TLS, socket, or a context deadline.

func (*ConnectionError) Error 

func (e *ConnectionError) Error() string

func (*ConnectionError) Unwrap 

func (e *ConnectionError) Unwrap() error

Unwrap lets errors.Is reach the underlying cause, so a caller can still test for context.DeadlineExceeded or a net error.

type DesignerSafeModeOptions added in v0.3.0 

type DesignerSafeModeOptions struct {
	AllowDeletingObjects     bool `json:"allowDeletingObjects"`
	AllowEditingAreaCapacity bool `json:"allowEditingAreaCapacity"`
}

type DesignerSafeModeOptionsParams added in v0.3.0 

type DesignerSafeModeOptionsParams struct {
	AllowDeletingObjects     *bool `json:"allowDeletingObjects,omitempty"`
	AllowEditingAreaCapacity *bool `json:"allowEditingAreaCapacity,omitempty"`
}

DesignerSafeModeOptionsParams is partial request input. Pointers preserve explicit false values without overriding an omitted server default.

type DesignerSession added in v0.3.0 

type DesignerSession struct {
	ID              string                  `json:"id"`
	Token           string                  `json:"token"`
	WorkspaceID     string                  `json:"workspaceId"`
	ChartID         string                  `json:"chartId"`
	AllowedOrigin   string                  `json:"allowedOrigin"`
	Authority       string                  `json:"authority"`
	CanEdit         bool                    `json:"canEdit"`
	CanPublish      bool                    `json:"canPublish"`
	Mode            string                  `json:"mode"`
	SafeModeOptions DesignerSafeModeOptions `json:"safeModeOptions"`
	FeaturePolicy   map[string]any          `json:"featurePolicy"`
	ExpiresAt       int64                   `json:"expiresAt"`
	DesignerURL     string                  `json:"designerUrl"`
}

type DesignerSessionEnvelope added in v0.3.0 

type DesignerSessionEnvelope struct {
	Session DesignerSession `json:"session"`
}

type DesignerSessionParams 

type DesignerSessionParams struct {
	WorkspaceID string
	// ChartID must already exist — create or copy a chart first.
	ChartID       string
	AllowedOrigin string
	// Authority is "read-only", "edit", or "publish".
	Authority string
	// CanPublish is the legacy authority flag; when supplied it must agree with
	// Authority. A pointer preserves an explicit false value.
	CanPublish *bool
	// Mode is "normal" or "safe".
	Mode string
	// SafeModeOptions is accepted only when Mode is "safe".
	SafeModeOptions *DesignerSafeModeOptionsParams
	// Features carries the Designer feature-policy object.
	Features         map[string]any
	ExpiresInSeconds int
}

DesignerSessionParams scopes an embedded-Designer token.

type EventChartUpdateParams added in v0.3.0 

type EventChartUpdateParams struct {
	AcknowledgeDroppedAssignments *bool
	Reason                        string
}

EventChartUpdateParams acknowledges assignment changes caused by a new chart.

type EventCreateNullableFields added in v0.3.0 

type EventCreateNullableFields struct {
	StartsAt      NullableField[int64]
	Venue         NullableField[string]
	ExternalRef   NullableField[string]
	Currency      NullableField[string]
	Description   NullableField[string]
	EndsAt        NullableField[int64]
	Timezone      NullableField[string]
	Locale        NullableField[string]
	PosterAssetID NullableField[string]
}

EventCreateNullableFields optionally overrides the convenience scalar fields on EventCreateParams when a caller must send explicit JSON null.

type EventCreateParams 

type EventCreateParams struct {
	// ChartID must reference a published chart.
	ChartID string
	Name    string
	Slug    string
	// StartsAt is epoch milliseconds.
	StartsAt    int64
	Venue       string
	ExternalRef string
	// Currency overrides the organisation currency for this event.
	Currency    string
	Description string
	// EndsAt is epoch milliseconds.
	EndsAt        int64
	Timezone      string
	Locale        string
	PosterAssetID string
	// Mode is normally inferred from the secret key; when supplied it must match.
	Mode           string
	IdempotencyKey string
	// Nullable overrides convenience scalar fields when explicit JSON null is
	// semantically different from omission.
	Nullable EventCreateNullableFields
}

EventCreateParams describes a new event.

type EventListParams 

type EventListParams struct {
	WorkspaceID string
	ExternalRef string
	// Limit is the page size. Clamped server-side; asking for more is not an error.
	Limit int
	// Cursor continues a previous page. Leave empty to start.
	Cursor string
	// NoCounts drops live availability counts, which cost the server one
	// round-trip per event. All sets this automatically.
	NoCounts bool
}

EventListParams filters and pages an event listing.

type EventLogEntry added in v0.3.0 

type EventLogEntry struct {
	ID     int64    `json:"id"`
	At     int64    `json:"at"`
	Action string   `json:"action"`
	Labels []string `json:"labels"`
	Ref    *string  `json:"ref"`
}

type EventLogListParams added in v0.3.0 

type EventLogListParams struct {
	Limit  int
	Before int64
}

EventLogListParams pages an event audit log newest first.

type EventLogPage added in v0.3.0 

type EventLogPage struct {
	Entries    []EventLogEntry `json:"entries"`
	NextBefore *int64          `json:"nextBefore"`
}

type EventsService 

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

EventsService covers event lifecycle, metadata and reports.

func (*EventsService) All 

func (s *EventsService) All(ctx context.Context, p *EventListParams) iter.Seq2[map[string]any, error]

All walks every event, paging transparently.

Counts are dropped by default here — you are walking the whole list, so per-event availability is rarely what you want and always what it costs.

func (*EventsService) Archive 

func (s *EventsService) Archive(ctx context.Context, eventKey string) (map[string]any, error)

Archive moves an event to the archive, preserving reporting.

func (*EventsService) Close 

func (s *EventsService) Close(ctx context.Context, eventKey string) (map[string]any, error)

Close stops buyer sales. Existing holds keep their TTL.

func (*EventsService) Create 

func (s *EventsService) Create(ctx context.Context, p EventCreateParams) (map[string]any, error)

Create makes an event from a published chart.

func (*EventsService) Delete 

func (s *EventsService) Delete(ctx context.Context, eventKey string) error

Delete soft-deletes an event.

func (*EventsService) DeletePoster added in v0.3.0 

func (s *EventsService) DeletePoster(
	ctx context.Context, eventKey string,
) (map[string]any, error)

DeletePoster removes the event poster used by share cards.

func (*EventsService) List 

func (s *EventsService) List(ctx context.Context, p *EventListParams) (Page, error)

List returns one page of events, including live availability counts unless NoCounts is set.

func (*EventsService) Reopen 

func (s *EventsService) Reopen(ctx context.Context, eventKey string) (map[string]any, error)

Reopen resumes buyer sales.

func (*EventsService) Retrieve 

func (s *EventsService) Retrieve(ctx context.Context, eventKey string) (map[string]any, error)

Retrieve fetches an event with live counts.

func (*EventsService) RetrieveHoldTTL 

func (s *EventsService) RetrieveHoldTTL(ctx context.Context, eventKey string) (map[string]any, error)

RetrieveHoldTTL reads the checkout window buyers get for this event.

func (*EventsService) RetrieveLog 

func (s *EventsService) RetrieveLog(
	ctx context.Context, eventKey string, options ...EventLogListParams,
) (EventLogPage, error)

RetrieveLog fetches one page of the event audit log.

func (*EventsService) RetrieveReport 

func (s *EventsService) RetrieveReport(ctx context.Context, eventKey string) (map[string]any, error)

RetrieveReport fetches the event report.

func (*EventsService) Update 

func (s *EventsService) Update(ctx context.Context, eventKey string, fields map[string]any) (map[string]any, error)

Update changes event metadata.

func (*EventsService) UpdateChart 

func (s *EventsService) UpdateChart(
	ctx context.Context, eventKey string, options ...EventChartUpdateParams,
) (map[string]any, error)

UpdateChart moves a live event onto the latest published version of its chart. The optional params value preserves the original no-argument call shape.

func (*EventsService) UpdateHoldTTL 

func (s *EventsService) UpdateHoldTTL(
	ctx context.Context, eventKey string, holdTTLMs ...int64,
) (map[string]any, error)

UpdateHoldTTL sets the checkout window in milliseconds. Omit holdTTLMs to send JSON null and restore the event default.

func (*EventsService) UpdatePoster added in v0.3.0 

func (s *EventsService) UpdatePoster(
	ctx context.Context, eventKey string, image []byte, contentType ...string,
) (map[string]any, error)

UpdatePoster uploads raw PNG, JPEG, or WebP bytes. Content type defaults to application/octet-stream; pass one explicit media type when it is known.

type HoldInspection added in v0.3.0 

type HoldInspection struct {
	HoldID          string          `json:"holdId"`
	Status          string          `json:"status"`
	ExpiresAt       int64           `json:"expiresAt"`
	BookingRef      *string         `json:"bookingRef"`
	EventKey        *string         `json:"eventKey"`
	Mode            string          `json:"mode"`
	ExternalRef     *string         `json:"externalRef"`
	WorkspaceID     *string         `json:"workspaceId"`
	Items           []InventoryItem `json:"items"`
	AccessSessionID *string         `json:"accessSessionId,omitempty"`
	AccessSource    string          `json:"accessSource,omitempty"`
	BuyerRef        *string         `json:"buyerRef,omitempty"`
	PartnerRef      *string         `json:"partnerRef,omitempty"`
}

HoldInspection is the secret-key projection returned by RetrieveHold.

type HoldParams 

type HoldParams struct {
	Labels []string
	// Selections is the alternative to Labels when you need a tier or a
	// quantity, e.g. a shared table or a GA area.
	Selections []map[string]any
	// TTLMs overrides the event's checkout window for this hold.
	TTLMs          int64
	ReplaceHoldID  string
	IdempotencyKey string
	// ChannelIDs grants access to private allocation inventory.
	ChannelIDs []string
	// IgnoreChannelRestrictions is a privileged backend override.
	IgnoreChannelRestrictions bool
	// Reason is written to the audit trail for channel use or an override.
	Reason string
}

HoldParams reserves specific objects by label.

type InventoryItem added in v0.3.0 

type InventoryItem struct {
	Label        string  `json:"label"`
	ObjectID     string  `json:"objectId"`
	ObjectType   string  `json:"objectType"`
	CategoryKey  string  `json:"categoryKey"`
	TierID       *string `json:"tierId"`
	UnitPrice    float64 `json:"unitPrice"`
	Currency     string  `json:"currency"`
	Quantity     *int    `json:"quantity,omitempty"`
	BookingMode  string  `json:"bookingMode,omitempty"`
	Capacity     *int    `json:"capacity,omitempty"`
	MinOccupancy *int    `json:"minOccupancy,omitempty"`
	MaxOccupancy *int    `json:"maxOccupancy,omitempty"`
	ChannelID    *string `json:"channelId,omitempty"`
	AccessSource string  `json:"accessSource,omitempty"`
	ReleaseID    *string `json:"releaseId,omitempty"`
}

InventoryItem is the authoritative priced object returned by hold APIs.

type InventoryService 

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

InventoryService covers holds, booking, blocking and availability.

Two complete flows, both first-class: 

browser holds → RetrieveHold for authoritative pricing → charge → Book(holdId)
backend books labels directly — box office, phone sales, comps

Never price from what the browser tells you. RetrieveHold is the authoritative answer, which is why it is a separate call.

func (*InventoryService) Block 

func (s *InventoryService) Block(
	ctx context.Context, eventKey string, labels []string, releaseAt ...int64,
) (map[string]any, error)

Block holds inventory back from sale (house seats, production holds).

func (*InventoryService) Book 

func (s *InventoryService) Book(ctx context.Context, eventKey string, p BookParams) (map[string]any, error)

Book confirms a sale.

func (*InventoryService) BookBestAvailable 

func (s *InventoryService) BookBestAvailable(
	ctx context.Context, eventKey string, p BestAvailableParams,
) (map[string]any, error)

BookBestAvailable picks and books in one call — the box-office shape.

Prefer this over hold-then-book when payment is already taken: a failure between two calls would strand inventory until the TTL expired.

func (*InventoryService) BoxOfficeBook 

func (s *InventoryService) BoxOfficeBook(
	ctx context.Context, eventKey string, labels []string, bookingRef string,
) (map[string]any, error)

BoxOfficeBook books named objects as a box-office sale.

func (*InventoryService) ExtendHold 

func (s *InventoryService) ExtendHold(
	ctx context.Context, eventKey, holdID string, ttlMs int64, access ...TrustedInventoryAccess,
) (map[string]any, error)

ExtendHold pushes an active hold's expiry out by a fresh window.

Use this rather than release-and-re-hold when an order takes longer than the checkout window — invoiced sales, a phone order on hold. Releasing first hands the seats to whoever is racing for them in between. A hold that is gone, expired, or at its renewal cap answers 409 cannot_extend.

func (*InventoryService) Hold 

func (s *InventoryService) Hold(ctx context.Context, eventKey string, p HoldParams) (map[string]any, error)

Hold reserves the named objects.

func (*InventoryService) HoldBestAvailable 

func (s *InventoryService) HoldBestAvailable(
	ctx context.Context, eventKey string, p BestAvailableParams,
) (map[string]any, error)

HoldBestAvailable picks the best free objects and holds them.

The picker is the one the buyer widget uses, so a phone order and a web order get the same answer for the same inventory.

func (*InventoryService) ListBookings added in v0.2.0 

func (s *InventoryService) ListBookings(
	ctx context.Context, eventKey string, p BookingListParams,
) (map[string]any, error)

ListBookings returns one page of booking lifecycle records, newest first.

func (*InventoryService) Release 

func (s *InventoryService) Release(
	ctx context.Context, eventKey string, labels []string, holdID string,
) (map[string]any, error)

Release frees held objects before the TTL expires.

func (*InventoryService) RetrieveAvailability 

func (s *InventoryService) RetrieveAvailability(ctx context.Context, eventKey string) (map[string]any, error)

RetrieveAvailability reads per-object availability rules.

func (*InventoryService) RetrieveBooking added in v0.2.0 

func (s *InventoryService) RetrieveBooking(
	ctx context.Context, eventKey, bookingRef string,
) (map[string]any, error)

RetrieveBooking returns a booking lifecycle by its stable reference.

func (*InventoryService) RetrieveHold 

func (s *InventoryService) RetrieveHold(
	ctx context.Context, eventKey, holdID string,
) (HoldInspection, error)

RetrieveHold returns authoritative items and prices. Charge from this, not from what the browser sent you.

func (*InventoryService) Unblock 

func (s *InventoryService) Unblock(ctx context.Context, eventKey string, labels []string) (map[string]any, error)

Unblock returns blocked objects to sale.

func (*InventoryService) UnblockAll 

func (s *InventoryService) UnblockAll(ctx context.Context, eventKey string) (map[string]any, error)

UnblockAll returns every blocked object in an event to sale.

func (*InventoryService) Unbook 

func (s *InventoryService) Unbook(
	ctx context.Context, eventKey string, labels []string, bookingRef string,
) (map[string]any, error)

Unbook reverses a booking. Requires a key with cancel authority.

func (*InventoryService) UpdateAvailability 

func (s *InventoryService) UpdateAvailability(
	ctx context.Context, eventKey string, fields map[string]any,
) (map[string]any, error)

UpdateAvailability replaces per-object availability rules.

type ManageCapability added in v0.3.0 

type ManageCapability string

ManageCapability is browser authority carried by a manage-session token. 

const (
	CapabilityView           ManageCapability = "event:view"
	CapabilityBlock          ManageCapability = "event:block"
	CapabilityCancel         ManageCapability = "event:cancel"
	CapabilityReports        ManageCapability = "event:reports"
	CapabilityChannelsView   ManageCapability = "event:channels:view"
	CapabilityChannelsManage ManageCapability = "event:channels:manage"
	CapabilityOrdersRead     ManageCapability = "event:orders:read"
	CapabilityRefund         ManageCapability = "event:refund"
	CapabilityTicketsSend    ManageCapability = "event:tickets:send"
	CapabilityDoorView       ManageCapability = "event:door:view"
	CapabilityDoorCheckin    ManageCapability = "event:door:checkin"
	CapabilityBoxOffice      ManageCapability = "event:boxoffice"
)

type ManageSession added in v0.3.0 

type ManageSession struct {
	ID            string             `json:"id"`
	Token         string             `json:"token"`
	ExpiresAt     int64              `json:"expiresAt"`
	EventKey      string             `json:"eventKey"`
	AllowedOrigin string             `json:"allowedOrigin"`
	Capabilities  []ManageCapability `json:"capabilities"`
}

type ManageSessionParams 

type ManageSessionParams struct {
	// AllowedOrigin is the https origin the token is bound to.
	AllowedOrigin string
	// Capabilities is required. See CreateManageSession for why.
	Capabilities []ManageCapability
	// ExpiresInSeconds is 300–14400. Defaults to 3600 server-side.
	ExpiresInSeconds int
	// WorkspaceID optionally confirms the event belongs to this workspace.
	WorkspaceID string
}

ManageSessionParams scopes a control-room token.

type NotFoundError 

type NotFoundError struct{ APIError }

NotFoundError is a 404, including another organisation's resource.

Asking for something owned by a different organisation answers 404, never 403: a 403 would confirm the resource exists, which is not something one customer should be able to learn about another.

type NullableField added in v0.3.0 

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

NullableField distinguishes an omitted request field from an explicit JSON null. Construct one with FieldValue or FieldNull; its internals stay private so the three states cannot be assembled inconsistently.

func FieldNull added in v0.3.0 

func FieldNull[T any]() NullableField[T]

FieldNull includes an explicit JSON null in a nullable request field.

func FieldValue added in v0.3.0 

func FieldValue[T any](value T) NullableField[T]

FieldValue includes value in a nullable request field.

type Option 

type Option func(*Client)

Option configures a Client.

func WithBaseURL 

func WithBaseURL(baseURL string) Option

WithBaseURL points the client at a different API host.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient supplies your own http.Client — for a custom transport, a proxy, or a test server. Its Timeout applies per attempt.

func WithMaxRetries 

func WithMaxRetries(attempts int) Option

WithMaxRetries sets total attempts for retryable failures.

type Page 

type Page struct {
	// Items are the rows on this page.
	Items []map[string]any
	// NextCursor is empty once the list is exhausted.
	NextCursor string
}

Page is one page of a list endpoint, plus the cursor for the next.

type RateLimitError 

type RateLimitError struct {
	APIError
	// RetryAfter is how long to wait, in seconds.
	RetryAfter float64
}

RateLimitError is a 429. RetryAfter prefers the header over the JSON field.

type SessionsService 

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

SessionsService mints short-lived, origin-bound browser tokens.

The governing rule: the SDK mints tokens, widgets consume them. Your secret key never reaches a browser.

func (*SessionsService) CreateDesignerSession 

func (s *SessionsService) CreateDesignerSession(
	ctx context.Context, p DesignerSessionParams,
) (DesignerSessionEnvelope, error)

CreateDesignerSession mints a token so an organiser can edit a chart inside your own UI.

func (*SessionsService) CreateManageSession 

func (s *SessionsService) CreateManageSession(
	ctx context.Context, eventKey string, p ManageSessionParams,
) (ManageSession, error)

CreateManageSession mints a manage-session token for the control room.

The raw API defaults an omitted list to view-only (event:view). This SDK still requires an explicit set so browser authority remains visible at every call site.

func (*SessionsService) RevokeDesignerSession 

func (s *SessionsService) RevokeDesignerSession(ctx context.Context, sessionID string) error

RevokeDesignerSession invalidates a designer token before it expires.

func (*SessionsService) RevokeManageSession 

func (s *SessionsService) RevokeManageSession(ctx context.Context, eventKey, sessionID string) error

RevokeManageSession invalidates a manage token before it expires.

type TrustedInventoryAccess added in v0.3.0 

type TrustedInventoryAccess struct {
	ChannelIDs []string
	// IgnoreChannelRestrictions is a privileged backend override.
	IgnoreChannelRestrictions bool
	// Reason is written to the audit trail for channel use or an override.
	Reason string
}

TrustedInventoryAccess carries private-allocation authority for trusted server inventory mutations.

type ValidationError 

type ValidationError struct{ APIError }

ValidationError is a 422 — the request was understood and rejected.

type WebhookCreateEnvelope added in v0.3.0 

type WebhookCreateEnvelope struct {
	Sub    WebhookSubscription `json:"sub"`
	Secret string              `json:"secret"`
}

type WebhookDelivery added in v0.3.0 

type WebhookDelivery struct {
	ID           string           `json:"id"`
	At           int64            `json:"at"`
	Event        WebhookEventName `json:"event"`
	Ref          *string          `json:"ref"`
	Status       int              `json:"status"`
	Attempt      int              `json:"attempt"`
	MaxAttempts  int              `json:"maxAttempts"`
	WillRetry    bool             `json:"willRetry"`
	OccurrenceID *string          `json:"occurrenceId"`
	Payload      any              `json:"payload"`
	ResponseBody *string          `json:"responseBody"`
	ErrorMessage *string          `json:"errorMessage"`
}

type WebhookDeliveryListParams added in v0.3.0 

type WebhookDeliveryListParams struct {
	Limit  int
	Status WebhookDeliveryStatus
	Before int64
}

WebhookDeliveryListParams filters and pages delivery attempts.

type WebhookDeliveryPage added in v0.3.0 

type WebhookDeliveryPage struct {
	Deliveries []WebhookDelivery `json:"deliveries"`
	NextBefore *int64            `json:"nextBefore,omitempty"`
}

type WebhookDeliveryStatus added in v0.3.0 

type WebhookDeliveryStatus string

WebhookDeliveryStatus filters webhook delivery attempts. 

const (
	WebhookDeliveryOK     WebhookDeliveryStatus = "ok"
	WebhookDeliveryFailed WebhookDeliveryStatus = "failed"
)

type WebhookEnvelope added in v0.3.0 

type WebhookEnvelope struct {
	Sub WebhookSubscription `json:"sub"`
}

type WebhookEventName added in v0.3.0 

type WebhookEventName string

WebhookEventName is one of the event names accepted by webhook create/update. 

const (
	WebhookEventSeatBooked   WebhookEventName = "seat.booked"
	WebhookEventSeatReleased WebhookEventName = "seat.released"
	WebhookEventSeatBlocked  WebhookEventName = "seat.blocked"
	WebhookEventHoldExpired  WebhookEventName = "hold.expired"
	WebhookEventHoldCreated  WebhookEventName = "hold.created"
	WebhookEventHoldExtended WebhookEventName = "hold.extended"
	WebhookEventEventCreated WebhookEventName = "event.created"
	WebhookEventEventSoldOut WebhookEventName = "event.soldout"
)

type WebhookList added in v0.3.0 

type WebhookList struct {
	Subs []WebhookSubscription `json:"subs"`
}

type WebhookSubscription added in v0.3.0 

type WebhookSubscription struct {
	ID          string             `json:"id"`
	URL         string             `json:"url"`
	Events      []WebhookEventName `json:"events"`
	Disabled    bool               `json:"disabled"`
	LastStatus  *string            `json:"lastStatus"`
	LastAt      *int64             `json:"lastAt"`
	CreatedAt   int64              `json:"createdAt"`
	Mode        *string            `json:"mode"`
	Environment *string            `json:"environment"`
	Uptime7d    *float64           `json:"uptime7d"`
}

WebhookSubscription is the public subscription projection. The signing secret is intentionally absent after creation.

type WebhookUpdateParams added in v0.3.0 

type WebhookUpdateParams struct {
	URL      string
	Events   []WebhookEventName
	Disabled *bool
}

WebhookUpdateParams describes the only mutable subscription fields.

type WebhooksService 

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

WebhooksService manages webhook subscriptions. To VERIFY a delivery, see VerifyWebhook.

func (*WebhooksService) Create 

func (s *WebhooksService) Create(
	ctx context.Context, targetURL string, events []WebhookEventName,
) (WebhookCreateEnvelope, error)

Create registers a subscription. The response carries the signing secret once.

func (*WebhooksService) Delete 

func (s *WebhooksService) Delete(ctx context.Context, webhookID string) error

Delete removes a subscription.

func (*WebhooksService) List 

func (s *WebhooksService) List(ctx context.Context) (WebhookList, error)

List returns the webhook subscriptions.

func (*WebhooksService) ListDeliveries 

func (s *WebhooksService) ListDeliveries(
	ctx context.Context, webhookID string, options ...WebhookDeliveryListParams,
) (WebhookDeliveryPage, error)

ListDeliveries returns recent delivery attempts for a subscription. The optional params value preserves the original no-filter call shape.

func (*WebhooksService) Update 

func (s *WebhooksService) Update(
	ctx context.Context, webhookID string, p WebhookUpdateParams,
) (WebhookEnvelope, error)

Update changes a subscription.

type WorkspaceCreateParams added in v0.3.0 

type WorkspaceCreateParams struct {
	Name           string
	ExternalRef    NullableField[string]
	IdempotencyKey string
}

WorkspaceCreateParams preserves omitted, valued, and explicit-null external references. Use FieldNull[string]() to request JSON null.

type WorkspacesService 

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

WorkspacesService manages workspaces, which isolate one tenant's charts and events from another's.

func (*WorkspacesService) Create 

func (s *WorkspacesService) Create(
	ctx context.Context, p WorkspaceCreateParams,
) (map[string]any, error)

Create provisions a workspace with exact nullable wire semantics.

func (*WorkspacesService) List 

func (s *WorkspacesService) List(ctx context.Context) (map[string]any, error)

List returns the organisation's workspaces.

func (*WorkspacesService) Retrieve 

func (s *WorkspacesService) Retrieve(ctx context.Context, workspaceID string) (map[string]any, error)

Retrieve fetches one workspace.

func (*WorkspacesService) Update 

func (s *WorkspacesService) Update(
	ctx context.Context, workspaceID string, fields map[string]any,
) (map[string]any, error)

Update renames, re-references, or disables a workspace.

The organisation's default workspace cannot be disabled — the API answers 409 default_workspace_required. Promote another one first.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.