apiv1

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Sep 6, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package apiv1 holds the public API's request and response types. They are shared by the Lambda that serves the API, the Go client used by the CLI and the MCP server, and the usage report embedded in the dashboard.

Index

Constants

View Source 
const (
	StatusScheduled  = "scheduled"
	StatusPending    = "pending"
	StatusProcessing = "processing"
	StatusPublished  = "published"
	StatusFailed     = "failed"
	StatusPartial    = "partial"
	StatusCancelled  = "cancelled"
)

Post statuses as exposed by the API (lower case, "published" instead of the internal SUCCESS).

View Source 
const (
	CodeUnauthorized         = "unauthorized"
	CodeInsufficientScope    = "insufficient_scope"
	CodeSubscriptionRequired = "subscription_required"
	CodeRateLimited          = "rate_limited"
	CodeQuotaExceeded        = "quota_exceeded"
	CodeValidation           = "validation_error"
	CodeNotFound             = "not_found"
	CodeInternal             = "internal_error"
)

Error codes returned in the error envelope.

View Source 
const DefaultBaseURL = "https://api.postatron.com"

DefaultBaseURL is the production API host.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	Status     int
	Code       string
	Message    string
	Details    map[string]any
	RetryAfter time.Duration
}

APIError is returned by Client for non-2xx responses.

func (*APIError) Error 

func (e *APIError) Error() string

type Account 

type Account struct {
	ID          string    `json:"id"`
	Platform    string    `json:"platform"`
	Username    string    `json:"username"`
	DisplayName string    `json:"display_name"`
	Status      string    `json:"status"`
	ConnectedAt time.Time `json:"connected_at"`
}

Account is a connected social account.

type AccountList 

type AccountList struct {
	Data []Account `json:"data"`
}

AccountList is the response of GET /v1/accounts.

type Client 

type Client struct {
	BaseURL    string
	APIKey     string
	HTTPClient *http.Client
	UserAgent  string
}

Client calls the public API with an API key.

func NewClient 

func NewClient(baseURL, apiKey string) *Client

NewClient returns a Client for baseURL (DefaultBaseURL when empty).

func (*Client) CreatePost 

func (c *Client) CreatePost(ctx context.Context, req CreatePostRequest) (*Post, error)

CreatePost calls POST /v1/posts.

func (*Client) DeletePost 

func (c *Client) DeletePost(ctx context.Context, id string) (*DeletePostResponse, error)

DeletePost calls DELETE /v1/posts/{id}.

func (*Client) GetPost 

func (c *Client) GetPost(ctx context.Context, id string) (*Post, error)

GetPost calls GET /v1/posts/{id}.

func (*Client) GetUsage 

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

GetUsage calls GET /v1/usage.

func (*Client) ListAccounts 

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

ListAccounts calls GET /v1/accounts.

func (*Client) ListPosts 

func (c *Client) ListPosts(ctx context.Context, query ListPostsQuery) (*PostList, error)

ListPosts calls GET /v1/posts.

type CreatePostRequest 

type CreatePostRequest struct {
	Content     string     `json:"content"`
	AccountIDs  []string   `json:"account_ids,omitempty"`
	Platforms   []string   `json:"platforms,omitempty"`
	ScheduledAt *time.Time `json:"scheduled_at,omitempty"`
}

CreatePostRequest is the body of POST /v1/posts. Exactly one of AccountIDs or Platforms must be set. ScheduledAt omitted publishes immediately.

type DeletePostResponse 

type DeletePostResponse struct {
	ID        string `json:"id"`
	Status    string `json:"status"`
	Cancelled bool   `json:"cancelled"`
	Message   string `json:"message,omitempty"`
}

DeletePostResponse is the response of DELETE /v1/posts/{id}.

type Delivery 

type Delivery struct {
	AccountID string `json:"account_id"`
	Platform  string `json:"platform"`
	Username  string `json:"username"`
	Status    string `json:"status"`
	URL       string `json:"url,omitempty"`
	Error     string `json:"error,omitempty"`
}

Delivery is the per-platform state of a post.

type ErrorBody 

type ErrorBody struct {
	Error ErrorDetail `json:"error"`
}

ErrorBody is the JSON envelope for every non-2xx response.

type ErrorDetail 

type ErrorDetail struct {
	Code    string         `json:"code"`
	Message string         `json:"message"`
	Details map[string]any `json:"details,omitempty"`
}

ErrorDetail carries a stable machine-readable code and a human message.

type ListPostsQuery 

type ListPostsQuery struct {
	Status   string
	Platform string
	From     *time.Time
	To       *time.Time
	Limit    int
	Cursor   string
}

ListPostsQuery holds the filters accepted by GET /v1/posts.

type Operations 

type Operations interface {
	CreatePost(ctx context.Context, req CreatePostRequest) (*Post, error)
	ListPosts(ctx context.Context, query ListPostsQuery) (*PostList, error)
	GetPost(ctx context.Context, id string) (*Post, error)
	DeletePost(ctx context.Context, id string) (*DeletePostResponse, error)
	ListAccounts(ctx context.Context) (*AccountList, error)
	GetUsage(ctx context.Context) (*UsageReport, error)
}

Operations is the six-operation surface. The Lambda implements it in process; Client implements it over HTTP; the MCP server and CLI consume it.

type Post 

type Post struct {
	ID           string     `json:"id"`
	Status       string     `json:"status"`
	Content      string     `json:"content"`
	MediaType    string     `json:"media_type"`
	ContainsLink bool       `json:"contains_link"`
	ScheduledAt  *time.Time `json:"scheduled_at,omitempty"`
	CreatedAt    time.Time  `json:"created_at"`
	UpdatedAt    *time.Time `json:"updated_at,omitempty"`
	Deliveries   []Delivery `json:"deliveries"`
}

Post is the API representation of a post.

type PostList 

type PostList struct {
	Data       []Post `json:"data"`
	NextCursor string `json:"next_cursor,omitempty"`
}

PostList is the response of GET /v1/posts.

type UsageCounter 

type UsageCounter struct {
	Used      int `json:"used"`
	Limit     int `json:"limit"`
	Remaining int `json:"remaining"`
}

UsageCounter is a capped counter. Limit is the amount included in the plan; the hard stop including any overage allowance is reported under Overage.

type UsageLinkCounter 

type UsageLinkCounter struct {
	Used int `json:"used"`
}

UsageLinkCounter counts link-containing destination-posts across all platforms.

type UsageOverage 

type UsageOverage struct {
	Enabled                     bool    `json:"enabled"`
	DestinationPosts            int     `json:"destination_posts"`
	XLinkPosts                  int     `json:"x_link_posts"`
	DestinationPostsCeiling     int     `json:"destination_posts_ceiling"`
	XLinkPostsCeiling           int     `json:"x_link_posts_ceiling"`
	DestinationPostUnitPriceUSD float64 `json:"destination_post_unit_price_usd"`
	XLinkPostUnitPriceUSD       float64 `json:"x_link_post_unit_price_usd"`
}

UsageOverage reports metered overage consumed this period and the hard ceilings (plan cap plus overage allowance on monthly plans).

type UsagePeriod 

type UsagePeriod struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

UsagePeriod is the calendar month the counters belong to.

type UsagePlan 

type UsagePlan struct {
	Code                 string `json:"code"`
	Name                 string `json:"name"`
	Interval             string `json:"interval"`
	Status               string `json:"status"`
	ConnectedAccounts    int    `json:"connected_accounts"`
	MaxConnectedAccounts int    `json:"max_connected_accounts"`
}

UsagePlan summarises the subscription the quota comes from.

type UsageRateLimits 

type UsageRateLimits struct {
	WritesPerHour  int `json:"writes_per_hour"`
	ReadsPerMinute int `json:"reads_per_minute"`
}

UsageRateLimits echoes the per-key limits applied to this plan.

type UsageReport 

type UsageReport struct {
	Period           UsagePeriod      `json:"period"`
	Plan             UsagePlan        `json:"plan"`
	DestinationPosts UsageCounter     `json:"destination_posts"`
	LinkPosts        UsageLinkCounter `json:"link_posts"`
	XLinkPosts       UsageCounter     `json:"x_link_posts"`
	ByPlatform       map[string]int   `json:"by_platform"`
	Overage          UsageOverage     `json:"overage"`
	RateLimits       UsageRateLimits  `json:"rate_limits"`
}

UsageReport is the response of GET /v1/usage. The dashboard renders the same structure.

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.