client

package module
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: May 9, 2025 License: Apache-2.0 Imports: 13 Imported by: 0

README

Outpost Go Client

Developer-friendly & type-safe Go client specifically catered to leverage the Outpost API.

Summary

Outpost API: The Outpost API is a REST-based JSON API for managing tenants, destinations, and publishing events.

Table of Contents

SDK Installation

To add the SDK as a dependency to your project:

go get github.com/hookdeck/outpost/sdks/go

SDK Example Usage

Example
package main

import (
	"client"
	"context"
	"log"
)

func main() {
	ctx := context.Background()

	s := client.New()

	res, err := s.Health.Check(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if res.Res != nil {
		// handle response
	}
}

Authentication

Per-Client Security Schemes

This SDK supports the following security schemes globally:

Name Type Scheme
AdminAPIKey http HTTP Bearer
TenantJwt http HTTP Bearer

You can set the security parameters through the WithSecurity option when initializing the SDK client instance. The selected scheme will be used by default to authenticate with the API for all operations that support it. For example:

package main

import (
	"client"
	"client/models/components"
	"context"
	"log"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithSecurity(components.Security{
			AdminAPIKey: client.String("<YOUR_BEARER_TOKEN_HERE>"),
		}),
	)

	res, err := s.Health.Check(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if res.Res != nil {
		// handle response
	}
}

Available Resources and Operations

Available methods
Destinations
  • List - List Destinations
  • Create - Create Destination
  • Get - Get Destination
  • Update - Update Destination
  • Delete - Delete Destination
  • Enable - Enable Destination
  • Disable - Disable Destination
Events
Health
Publish
Schemas
Tenants
Topics
  • List - List Available Topics (for Tenant)
  • ListJwt - List Available Topics)

Global Parameters

A parameter is configured globally. This parameter may be set on the SDK client instance itself during initialization. When configured as an option during SDK initialization, This global value will be used as the default on the operations that use it. When such operations are called, there is a place in each to override the global value, if needed.

For example, you can set tenant_id to "<id>" at SDK initialization and then you do not have to pass the same value on calls to operations like Upsert. But if you want to do so you may, which will locally override the global setting. See the example code below for a demonstration.

Available Globals

The following global parameter is available.

Name Type Description
TenantID string The TenantID parameter.
Example
package main

import (
	"client"
	"client/models/components"
	"context"
	"log"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithSecurity(components.Security{
			AdminAPIKey: client.String("<YOUR_BEARER_TOKEN_HERE>"),
		}),
	)

	res, err := s.Tenants.Upsert(ctx, client.String("<id>"))
	if err != nil {
		log.Fatal(err)
	}
	if res.Tenant != nil {
		// handle response
	}
}

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retry.Config object to the call by using the WithRetries option:

package main

import (
	"client"
	"client/retry"
	"context"
	"log"
	"models/operations"
)

func main() {
	ctx := context.Background()

	s := client.New()

	res, err := s.Health.Check(ctx, operations.WithRetries(
		retry.Config{
			Strategy: "backoff",
			Backoff: &retry.BackoffStrategy{
				InitialInterval: 1,
				MaxInterval:     50,
				Exponent:        1.1,
				MaxElapsedTime:  100,
			},
			RetryConnectionErrors: false,
		}))
	if err != nil {
		log.Fatal(err)
	}
	if res.Res != nil {
		// handle response
	}
}

If you'd like to override the default retry strategy for all operations that support retries, you can use the WithRetryConfig option at SDK initialization:

package main

import (
	"client"
	"client/retry"
	"context"
	"log"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithRetryConfig(
			retry.Config{
				Strategy: "backoff",
				Backoff: &retry.BackoffStrategy{
					InitialInterval: 1,
					MaxInterval:     50,
					Exponent:        1.1,
					MaxElapsedTime:  100,
				},
				RetryConnectionErrors: false,
			}),
	)

	res, err := s.Health.Check(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if res.Res != nil {
		// handle response
	}
}

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or an error, they will never return both.

By Default, an API error will return apierrors.APIError. When custom error responses are specified for an operation, the SDK may also return their associated error. You can refer to respective Errors tables in SDK docs for more details on possible error types for each operation.

For example, the Check function may return the following errors:

Error Type Status Code Content Type
apierrors.NotFoundError 404 application/json
apierrors.UnauthorizedError 401, 403, 407 application/json
apierrors.TimeoutError 408 application/json
apierrors.RateLimitedError 429 application/json
apierrors.BadRequestError 400, 413, 414, 415, 422, 431 application/json
apierrors.TimeoutError 504 application/json
apierrors.NotFoundError 501, 505 application/json
apierrors.InternalServerError 500, 502, 503, 506, 507, 508 application/json
apierrors.BadRequestError 510 application/json
apierrors.UnauthorizedError 511 application/json
apierrors.APIError 4XX, 5XX */*
Example
package main

import (
	"client"
	"client/models/apierrors"
	"context"
	"errors"
	"log"
)

func main() {
	ctx := context.Background()

	s := client.New()

	res, err := s.Health.Check(ctx)
	if err != nil {

		var e *apierrors.NotFoundError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.UnauthorizedError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.TimeoutError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.RateLimitedError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.BadRequestError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.TimeoutError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.NotFoundError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.InternalServerError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.BadRequestError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.UnauthorizedError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}

		var e *apierrors.APIError
		if errors.As(err, &e) {
			// handle error
			log.Fatal(e.Error())
		}
	}
}

Server Selection

Override Server URL Per-Client

The default server can be overridden globally using the WithServerURL(serverURL string) option when initializing the SDK client instance. For example:

package main

import (
	"client"
	"context"
	"log"
)

func main() {
	ctx := context.Background()

	s := client.New(
		client.WithServerURL("http://localhost:3333/api/v1"),
	)

	res, err := s.Health.Check(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if res.Res != nil {
		// handle response
	}
}

Custom HTTP Client

The Go SDK makes API calls that wrap an internal HTTP client. The requirements for the HTTP client are very simple. It must match this interface:

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

The built-in net/http client satisfies this interface and a default client based on the built-in is provided by default. To replace this default with a client of your own, you can implement this interface yourself or provide your own client configured as desired. Here's a simple example, which adds a client with a 30 second timeout.

import (
	"net/http"
	"time"
	"github.com/myorg/your-go-sdk"
)

var (
	httpClient = &http.Client{Timeout: 30 * time.Second}
	sdkClient  = sdk.New(sdk.WithClient(httpClient))
)

This can be a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration.

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

SDK Created by Speakeasy

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ServerList = []string{

	"http://localhost:3333/api/v1",
}

ServerList contains the list of servers available to the SDK

Functions

func Bool 

func Bool(b bool) *bool

Bool provides a helper function to return a pointer to a bool

func Float32 

func Float32(f float32) *float32

Float32 provides a helper function to return a pointer to a float32

func Float64 

func Float64(f float64) *float64

Float64 provides a helper function to return a pointer to a float64

func Int 

func Int(i int) *int

Int provides a helper function to return a pointer to an int

func Int64 

func Int64(i int64) *int64

Int64 provides a helper function to return a pointer to an int64

func Pointer 

func Pointer[T any](v T) *T

Pointer provides a helper function to return a pointer to a type

func String 

func String(s string) *string

String provides a helper function to return a pointer to a string

Types

type Destinations 

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

Destinations are the endpoints where events are sent. Each destination is associated with a tenant and can be configured to receive specific event topics.

```json 

{
  "id": "des_12345", // Control plane generated ID or user provided ID
  "type": "webhooks", // Type of the destination
  "topics": ["user.created", "user.updated"], // Topics of events this destination is eligible for
  "config": {
    // Destination type specific configuration. Schema of depends on type
    "url": "https://example.com/webhooks/user"
  },
  "credentials": {
    // Destination type specific credentials. AES encrypted. Schema depends on type
    "secret": "some***********"
  },
  "disabled_at": null, // null or ISO date if disabled
  "created_at": "2024-01-01T00:00:00Z" // Date the destination was created
}

```

The `topics` array can contain either a list of topics or a wildcard `*` implying that all topics are supported. If you do not wish to implement topics for your application, you set all destination topics to `*`.

By default all destination `credentials` are obfuscated and the values cannot be read. This does not apply to the `webhook` type destination secret and each destination can expose their own obfuscation logic.

func (*Destinations) Create 

func (s *Destinations) Create(ctx context.Context, destinationCreate components.DestinationCreate, tenantID *string, opts ...operations.Option) (*operations.CreateTenantDestinationResponse, error)

Create Destination Creates a new destination for the tenant. The request body structure depends on the `type`.

func (*Destinations) Delete 

func (s *Destinations) Delete(ctx context.Context, destinationID string, tenantID *string, opts ...operations.Option) (*operations.DeleteTenantDestinationResponse, error)

Delete Destination Deletes a specific destination.

func (*Destinations) Disable 

func (s *Destinations) Disable(ctx context.Context, destinationID string, tenantID *string, opts ...operations.Option) (*operations.DisableTenantDestinationResponse, error)

Disable Destination Disables a previously enabled destination.

func (*Destinations) Enable 

func (s *Destinations) Enable(ctx context.Context, destinationID string, tenantID *string, opts ...operations.Option) (*operations.EnableTenantDestinationResponse, error)

Enable Destination Enables a previously disabled destination.

func (*Destinations) Get 

func (s *Destinations) Get(ctx context.Context, destinationID string, tenantID *string, opts ...operations.Option) (*operations.GetTenantDestinationResponse, error)

Get Destination Retrieves details for a specific destination.

func (*Destinations) List 

func (s *Destinations) List(ctx context.Context, tenantID *string, type_ *operations.Type, topics *operations.Topics, opts ...operations.Option) (*operations.ListTenantDestinationsResponse, error)

List Destinations Return a list of the destinations for the tenant. The endpoint is not paged.

func (*Destinations) Update 

func (s *Destinations) Update(ctx context.Context, destinationID string, destinationUpdate components.DestinationUpdate, tenantID *string, opts ...operations.Option) (*operations.UpdateTenantDestinationResponse, error)

Update Destination Updates the configuration of an existing destination. The request body structure depends on the destination's `type`. Type itself cannot be updated. May return an OAuth redirect URL for certain types.

type Events 

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

Events - Operations related to event history and deliveries.

func (*Events) Get 

func (s *Events) Get(ctx context.Context, eventID string, tenantID *string, opts ...operations.Option) (*operations.GetTenantEventResponse, error)

Get Event Retrieves details for a specific event.

func (*Events) GetByDestination 

func (s *Events) GetByDestination(ctx context.Context, destinationID string, eventID string, tenantID *string, opts ...operations.Option) (*operations.GetTenantEventByDestinationResponse, error)

GetByDestination - Get Event by Destination Retrieves a specific event associated with a specific destination for the tenant.

func (*Events) List 

func (s *Events) List(ctx context.Context, tenantID *string, destinationID *operations.DestinationID, status *operations.ListTenantEventsStatus, opts ...operations.Option) (*operations.ListTenantEventsResponse, error)

List Events Retrieves a list of events for the tenant, supporting cursor navigation (details TBD) and filtering.

func (*Events) ListByDestination 

func (s *Events) ListByDestination(ctx context.Context, destinationID string, tenantID *string, status *operations.ListTenantEventsByDestinationStatus, opts ...operations.Option) (*operations.ListTenantEventsByDestinationResponse, error)

ListByDestination - List Events by Destination Retrieves events associated with a specific destination for the tenant.

func (*Events) ListDeliveries 

func (s *Events) ListDeliveries(ctx context.Context, eventID string, tenantID *string, opts ...operations.Option) (*operations.ListTenantEventDeliveriesResponse, error)

ListDeliveries - List Event Delivery Attempts Retrieves a list of delivery attempts for a specific event, including response details.

func (*Events) Retry 

func (s *Events) Retry(ctx context.Context, destinationID string, eventID string, tenantID *string, opts ...operations.Option) (*operations.RetryTenantEventResponse, error)

Retry Event Delivery Triggers a retry for a failed event delivery.

type HTTPClient 

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient provides an interface for suplying the SDK with a custom HTTP client

type Health 

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

API Health Check

func (*Health) Check 

func (s *Health) Check(ctx context.Context, opts ...operations.Option) (*operations.HealthCheckResponse, error)

Health Check Simple health check endpoint.

type Outpost 

type Outpost struct {
	// API Health Check
	Health *Health
	// The API segments resources per `tenant`. A tenant represents a user/team/organization in your product. The provided value determines the tenant's ID, which can be any string representation.
	//
	// If your system is not multi-tenant, create a single tenant with a hard-code tenant ID upon initialization. If your system has a single tenant but multiple environments, create a tenant per environment, like `live` and `test`.
	//
	Tenants *Tenants
	// Destinations are the endpoints where events are sent. Each destination is associated with a tenant and can be configured to receive specific event topics.
	//
	// “`json
	// {
	//   "id": "des_12345", // Control plane generated ID or user provided ID
	//   "type": "webhooks", // Type of the destination
	//   "topics": ["user.created", "user.updated"], // Topics of events this destination is eligible for
	//   "config": {
	//     // Destination type specific configuration. Schema of depends on type
	//     "url": "https://example.com/webhooks/user"
	//   },
	//   "credentials": {
	//     // Destination type specific credentials. AES encrypted. Schema depends on type
	//     "secret": "some***********"
	//   },
	//   "disabled_at": null, // null or ISO date if disabled
	//   "created_at": "2024-01-01T00:00:00Z" // Date the destination was created
	// }
	// “`
	//
	// The `topics` array can contain either a list of topics or a wildcard `*` implying that all topics are supported. If you do not wish to implement topics for your application, you set all destination topics to `*`.
	//
	// By default all destination `credentials` are obfuscated and the values cannot be read. This does not apply to the `webhook` type destination secret and each destination can expose their own obfuscation logic.
	//
	Destinations *Destinations
	// Operations for publishing events.
	Publish *Publish
	// Operations for retrieving destination type schemas.
	Schemas *Schemas
	// Operations for retrieving available event topics.
	Topics *Topics
	// Operations related to event history and deliveries.
	Events *Events
	// contains filtered or unexported fields
}

Outpost API: The Outpost API is a REST-based JSON API for managing tenants, destinations, and publishing events.

func New 

func New(opts ...SDKOption) *Outpost

New creates a new instance of the SDK with the provided options

type Publish 

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

Publish - Operations for publishing events.

func (*Publish) Event 

func (s *Publish) Event(ctx context.Context, request components.PublishRequest, opts ...operations.Option) (*operations.PublishEventResponse, error)

Publish Event Publishes an event to the specified topic, potentially routed to a specific destination. Requires Admin API Key.

type SDKOption 

type SDKOption func(*Outpost)

func WithClient 

func WithClient(client HTTPClient) SDKOption

WithClient allows the overriding of the default HTTP client used by the SDK

func WithRetryConfig 

func WithRetryConfig(retryConfig retry.Config) SDKOption

func WithSecurity 

func WithSecurity(security components.Security) SDKOption

WithSecurity configures the SDK to use the provided security details

func WithSecuritySource 

func WithSecuritySource(security func(context.Context) (components.Security, error)) SDKOption

WithSecuritySource configures the SDK to invoke the Security Source function on each method call to determine authentication

func WithServerIndex 

func WithServerIndex(serverIndex int) SDKOption

WithServerIndex allows the overriding of the default server by index

func WithServerURL 

func WithServerURL(serverURL string) SDKOption

WithServerURL allows the overriding of the default server URL

func WithTemplatedServerURL 

func WithTemplatedServerURL(serverURL string, params map[string]string) SDKOption

WithTemplatedServerURL allows the overriding of the default server URL with a templated URL populated with the provided parameters

func WithTenantID 

func WithTenantID(tenantID string) SDKOption

WithTenantID allows setting the TenantID parameter for all supported operations

func WithTimeout 

func WithTimeout(timeout time.Duration) SDKOption

WithTimeout Optional request timeout applied to each operation

type Schemas 

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

Schemas - Operations for retrieving destination type schemas.

func (*Schemas) Get 

func (s *Schemas) Get(ctx context.Context, type_ operations.GetTenantDestinationTypeSchemaType, tenantID *string, opts ...operations.Option) (*operations.GetTenantDestinationTypeSchemaResponse, error)

Get Destination Type Schema (for Tenant) Returns the input schema for a specific destination type. Requires Admin API Key or Tenant JWT.

func (*Schemas) GetDestinationTypeJwt 

func (s *Schemas) GetDestinationTypeJwt(ctx context.Context, type_ operations.GetDestinationTypeSchemaType, opts ...operations.Option) (*operations.GetDestinationTypeSchemaResponse, error)

GetDestinationTypeJwt - Get Destination Type Schema Returns the input schema for a specific destination type.

func (*Schemas) ListDestinationTypesJwt 

func (s *Schemas) ListDestinationTypesJwt(ctx context.Context, opts ...operations.Option) (*operations.ListDestinationTypeSchemasJwtResponse, error)

ListDestinationTypesJwt - List Destination Type Schemas (JWT Auth) Returns a list of JSON-based input schemas for each available destination type (infers tenant from JWT).

func (*Schemas) ListTenantDestinationTypes 

func (s *Schemas) ListTenantDestinationTypes(ctx context.Context, tenantID *string, opts ...operations.Option) (*operations.ListTenantDestinationTypeSchemasResponse, error)

ListTenantDestinationTypes - List Destination Type Schemas (for Tenant) Returns a list of JSON-based input schemas for each available destination type. Requires Admin API Key or Tenant JWT.

type Tenants 

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

Tenants - The API segments resources per `tenant`. A tenant represents a user/team/organization in your product. The provided value determines the tenant's ID, which can be any string representation.

If your system is not multi-tenant, create a single tenant with a hard-code tenant ID upon initialization. If your system has a single tenant but multiple environments, create a tenant per environment, like `live` and `test`.

func (*Tenants) Delete 

func (s *Tenants) Delete(ctx context.Context, tenantID *string, opts ...operations.Option) (*operations.DeleteTenantResponse, error)

Delete Tenant Deletes the tenant and all associated destinations.

func (*Tenants) Get 

func (s *Tenants) Get(ctx context.Context, tenantID *string, opts ...operations.Option) (*operations.GetTenantResponse, error)

Get Tenant Retrieves details for a specific tenant.

func (*Tenants) GetPortalURL 

func (s *Tenants) GetPortalURL(ctx context.Context, tenantID *string, theme *operations.Theme, opts ...operations.Option) (*operations.GetTenantPortalURLResponse, error)

GetPortalURL - Get Portal Redirect URL Returns a redirect URL containing a JWT to authenticate the user with the portal.

func (*Tenants) GetToken 

func (s *Tenants) GetToken(ctx context.Context, tenantID *string, opts ...operations.Option) (*operations.GetTenantTokenResponse, error)

GetToken - Get Tenant JWT Token Returns a JWT token scoped to the tenant for safe browser API calls.

func (*Tenants) Upsert 

func (s *Tenants) Upsert(ctx context.Context, tenantID *string, opts ...operations.Option) (*operations.UpsertTenantResponse, error)

Upsert - Create or Update Tenant Idempotently creates or updates a tenant. Required before associating destinations.

type Topics 

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

Topics - Operations for retrieving available event topics.

func (*Topics) List 

func (s *Topics) List(ctx context.Context, tenantID *string, opts ...operations.Option) (*operations.ListTenantTopicsResponse, error)

List Available Topics (for Tenant) Returns a list of available event topics configured in the Outpost instance. Requires Admin API Key or Tenant JWT.

func (*Topics) ListJwt 

func (s *Topics) ListJwt(ctx context.Context, opts ...operations.Option) (*operations.ListTopicsResponse, error)

ListJwt - List Available Topics) Returns a list of available event topics configured in the Outpost instance.

Source Files

View all Source files

Directories

Path Synopsis
internal
globals
hooks
utils
models
apierrors
components
operations

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.