@apollo-deploy/tesseract 1.9.0 → 2.0.0

package/templates/go/client.hbs

@@ -1,93 +1,75 @@
 package {{pkgName}}
 
 import (
+{{#if hasSSE}}
 	"context"
+{{/if}}
 	"time"
 )
 
-// ── Client Configuration ──────────────────────────────────────────────────
-
-// ClientConfig holds all configuration for the API client.
+// ClientConfig configures the API client.
 type ClientConfig struct {
-	BaseURL        string
-	Timeout        time.Duration
-	MaxRetries     int
-	DefaultHeaders map[string]string
+	BaseURL string
+{{#each securitySchemes}}
+	{{pascalCase configKey}} string
+{{/each}}
+	Timeout             time.Duration
+	MaxRetries          int
+	RetryUnsafeRequests bool
+	DefaultHeaders      map[string]string
 }
 
-// ClientOption is a functional option for configuring the client.
 type ClientOption func(*ClientConfig)
 
-// WithBaseURL sets the base URL for all API requests.
-func WithBaseURL(url string) ClientOption {
-	return func(c *ClientConfig) { c.BaseURL = url }
+func WithBaseURL(url string) ClientOption { return func(c *ClientConfig) { c.BaseURL = url } }
+func WithTimeout(timeout time.Duration) ClientOption { return func(c *ClientConfig) { c.Timeout = timeout } }
+func WithMaxRetries(retries int) ClientOption { return func(c *ClientConfig) { c.MaxRetries = retries } }
+func WithUnsafeRetries(enabled bool) ClientOption {
+	return func(c *ClientConfig) { c.RetryUnsafeRequests = enabled }
 }
-
-// WithTimeout sets the request timeout.
-func WithTimeout(d time.Duration) ClientOption {
-	return func(c *ClientConfig) { c.Timeout = d }
-}
-
-// WithMaxRetries sets the maximum number of retry attempts.
-func WithMaxRetries(n int) ClientOption {
-	return func(c *ClientConfig) { c.MaxRetries = n }
-}
-
-// WithDefaultHeader adds a default header sent with every request.
 func WithDefaultHeader(key, value string) ClientOption {
 	return func(c *ClientConfig) {
-		if c.DefaultHeaders == nil {
-			c.DefaultHeaders = make(map[string]string)
-		}
+		if c.DefaultHeaders == nil { c.DefaultHeaders = make(map[string]string) }
 		c.DefaultHeaders[key] = value
 	}
 }
+{{#each securitySchemes}}
+func With{{pascalCase configKey}}(value string) ClientOption {
+	return func(c *ClientConfig) { c.{{pascalCase configKey}} = value }
+}
+{{/each}}
 
-// DefaultConfig returns a ClientConfig populated with sensible defaults.
 func DefaultConfig() ClientConfig {
 	return ClientConfig{
-		BaseURL:    "{{baseUrl}}",
-		Timeout:    15 * time.Second,
-		MaxRetries: 3,
+		BaseURL: "{{baseUrl}}", Timeout: 15 * time.Second, MaxRetries: 3,
 	}
 }
 
-// ── Client ────────────────────────────────────────────────────────────────
-
-// Client is the primary API client for {{title}}.
-// It is safe for concurrent use by multiple goroutines.
+// Client is safe for concurrent use by multiple goroutines.
 type Client struct {
-	config    ClientConfig
+	config ClientConfig
 	transport *Transport
 {{#each groups}}
 	{{pascalCase name}} *{{interfaceName}}
 {{/each}}
 }
 
-// NewClient creates a new {{title}} API client with the given options.
-//
-// Example:
-//
-//	client := petshop.NewClient(
-//	    petshop.WithBaseURL("https://api.example.com"),
-//	    petshop.WithTimeout(30*time.Second),
-//	)
-//	pets, err := client.Pets.List(ctx, nil)
 func NewClient(opts ...ClientOption) *Client {
 	cfg := DefaultConfig()
-	for _, opt := range opts {
-		opt(&cfg)
-	}
-
+	for _, option := range opts { option(&cfg) }
 	t := NewTransport(TransportConfig{
-		BaseURL:    cfg.BaseURL,
-		Timeout:    cfg.Timeout,
+		BaseURL: cfg.BaseURL,
+{{#each securitySchemes}}
+		{{pascalCase configKey}}: cfg.{{pascalCase configKey}},
+{{/each}}
+		Timeout: cfg.Timeout,
 		MaxRetries: cfg.MaxRetries,
-		Headers:    cfg.DefaultHeaders,
+		RetryUnsafeRequests: cfg.RetryUnsafeRequests,
+		Headers: cfg.DefaultHeaders,
+		UserAgent: "{{pkgName}}-go-sdk/{{packageVersion}}",
 	})
-
 	return &Client{
-		config:    cfg,
+		config: cfg,
 		transport: t,
 {{#each groups}}
 		{{pascalCase name}}: &{{interfaceName}}{transport: t},
@@ -95,64 +77,17 @@ func NewClient(opts ...ClientOption) *Client {
 	}
 }
 
-// Transport returns the underlying HTTP transport for advanced use cases.
-func (c *Client) Transport() *Transport {
-	return c.transport
-}
+func (c *Client) Transport() *Transport { return c.transport }
+func (c *Client) CloseIdleConnections() { c.transport.CloseIdleConnections() }
 
-// ── Request / Response types ──────────────────────────────────────────────
-
-// RequestOptions holds per-request overrides.
-type RequestOptions struct {
-	// Timeout overrides the client-level timeout for this request.
-	Timeout time.Duration
-	// Headers are additional headers merged into the request.
-	Headers map[string]string
-}
-
-// ListParams is embedded by list operation parameter types to provide
-// common pagination and filtering fields.
-type ListParams struct {
-	Page  *int    `json:"page,omitempty"`
-	Limit *int    `json:"limit,omitempty"`
-}
-
-// Int returns a pointer to the given int value. Useful for optional
-// parameters in request structs.
-func Int(v int) *int { return &v }
-
-// String returns a pointer to the given string value.
-func String(v string) *string { return &v }
-
-// Bool returns a pointer to the given bool value.
-func Bool(v bool) *bool { return &v }
+func Int(value int) *int { return &value }
+func String(value string) *string { return &value }
+func Bool(value bool) *bool { return &value }
 
 {{#if hasSSE}}
-// ── SSE Types ─────────────────────────────────────────────────────────────
-
-// SSEEvent represents a parsed Server-Sent Event.
-type SSEEvent struct {
-	Event string
-	Data  string
-	ID    string
-	Retry int
-}
-
-// SSEOption configures an SSE stream subscription.
+type SSEEvent struct { Event, Data, ID string; Retry int }
 type SSEOption func(*sseConfig)
-
-type sseConfig struct {
-	signal    context.Context
-	eventTypes []string
-}
-
-// WithSSESignal sets a context for cancellation of the SSE stream.
-func WithSSESignal(ctx context.Context) SSEOption {
-	return func(c *sseConfig) { c.signal = ctx }
-}
-
-// WithSSEEventTypes filters the stream to specific event types.
-func WithSSEEventTypes(types ...string) SSEOption {
-	return func(c *sseConfig) { c.eventTypes = types }
-}
+type sseConfig struct { signal context.Context; eventTypes []string }
+func WithSSESignal(ctx context.Context) SSEOption { return func(c *sseConfig) { c.signal = ctx } }
+func WithSSEEventTypes(types ...string) SSEOption { return func(c *sseConfig) { c.eventTypes = types } }
 {{/if}}

package/templates/go/domain.hbs

@@ -4,6 +4,12 @@ import (
 {{#if hasSSE}}
 	"bufio"
 	"strings"
+{{/if}}
+{{#if needsFormatting}}
+	"fmt"
+{{/if}}
+{{#if hasQueryParams}}
+	"net/url"
 {{/if}}
 	"context"
 )
@@ -15,22 +21,53 @@ type {{interfaceName}} struct {
 
 {{#each operations}}
 {{#if isEventStream}}
-func (api *{{../interfaceName}}) {{pascalCase name}}Stream(
+func (api *{{../interfaceName}}) {{pascalCase name}}(
 	ctx context.Context,
 {{#each pathParams}}
-	{{name}} string,
+	{{name}} {{targetType}},
 {{/each}}
-{{#if queryType}}
-	params {{goQueryType queryType}},
+{{#if requestBody}}
+	body {{requestBody.inputType}},
 {{/if}}
+{{#each queryParams}}
+	{{name}} {{inputType}},
+{{/each}}
+{{#each headerParams}}
+	{{name}} {{inputType}},
+{{/each}}
 ) (<-chan SSEEvent, <-chan error) {
 	eventCh := make(chan SSEEvent)
 	errCh := make(chan error, 1)
 	go func() {
 		defer close(eventCh)
 		defer close(errCh)
-		reqPath := buildPath("{{path}}"{{#each pathParams}}, "{{originalName}}", {{name}}{{/each}})
-		resp, err := api.transport.Stream(ctx, request{Method: "{{httpMethod}}", Path: reqPath})
+		reqPath := buildPath("{{path}}"{{#each pathParams}}, "{{name}}", {{name}}{{/each}})
+{{#if hasQueryParams}}
+		query := url.Values{}
+{{#each queryParams}}
+{{#if required}}
+		query.Set("{{originalName}}", fmt.Sprint({{name}}))
+{{else}}
+		if {{name}} != nil { query.Set("{{originalName}}", fmt.Sprint(*{{name}})) }
+{{/if}}
+{{/each}}
+{{/if}}
+{{#if hasHeaderParams}}
+		headers := map[string]string{}
+{{#each headerParams}}
+{{#if required}}
+		headers["{{originalName}}"] = fmt.Sprint({{name}})
+{{else}}
+		if {{name}} != nil { headers["{{originalName}}"] = fmt.Sprint(*{{name}}) }
+{{/if}}
+{{/each}}
+{{/if}}
+		resp, err := api.transport.Stream(ctx, request{
+			Method: "{{httpMethod}}", Path: reqPath,
+{{#if hasQueryParams}}			Query: query,{{/if}}
+{{#if requestBody}}			Body: body, ContentType: "{{requestBody.contentType}}",{{/if}}
+{{#if hasHeaderParams}}			Headers: headers,{{/if}}
+		})
 		if err != nil { errCh <- err; return }
 		defer resp.Body.Close()
 		scanner := bufio.NewScanner(resp.Body)
@@ -49,6 +86,8 @@ func (api *{{../interfaceName}}) {{pascalCase name}}Stream(
 			if strings.HasPrefix(line, "data:") { if current.Data != "" { current.Data += "\n" }; current.Data += strings.TrimSpace(line[5:]) }
 			if strings.HasPrefix(line, "id:") { current.ID = strings.TrimSpace(line[3:]) }
 		}
+		if current.Data != "" { eventCh <- current }
+		if err := scanner.Err(); err != nil { errCh <- err }
 	}()
 	return eventCh, errCh
 }
@@ -57,31 +96,50 @@ func (api *{{../interfaceName}}) {{pascalCase name}}Stream(
 func (api *{{../interfaceName}}) {{pascalCase name}}(
 	ctx context.Context,
 {{#each pathParams}}
-	{{name}} string,
+	{{name}} {{targetType}},
 {{/each}}
 {{#if requestBody}}
-	body *{{requestBody.type}},
+	body {{requestBody.inputType}},
 {{/if}}
-{{#if queryType}}
-	params {{goQueryType queryType}},
+{{#each queryParams}}
+	{{name}} {{inputType}},
+{{/each}}
+{{#each headerParams}}
+	{{name}} {{inputType}},
+{{/each}}
+) {{#if (eq responseType "void")}}error{{else}}(*{{goResponseType}}, error){{/if}} {
+	reqPath := buildPath("{{path}}"{{#each pathParams}}, "{{name}}", {{name}}{{/each}})
+{{#if hasQueryParams}}
+	query := url.Values{}
+{{#each queryParams}}
+{{#if required}}
+	query.Set("{{originalName}}", fmt.Sprint({{name}}))
+{{else}}
+	if {{name}} != nil { query.Set("{{originalName}}", fmt.Sprint(*{{name}})) }
 {{/if}}
-) {{#if (eq responseType "void")}}error{{else}}(*{{responseType}}, error){{/if}} {
-	reqPath := buildPath("{{path}}"{{#each pathParams}}, "{{originalName}}", {{name}}{{/each}})
-	{{#if queryType}}q := buildQuery(params){{/if}}
-{{#if (eq responseType "void")}}
-	return api.transport.Execute(ctx, request{
-		Method: "{{httpMethod}}", Path: reqPath,
-{{#if queryType}}		Query: q,{{/if}}
-{{#if requestBody}}		Body: body,{{/if}}
-	}, nil)
+{{/each}}
+{{/if}}
+{{#if hasHeaderParams}}
+	headers := map[string]string{}
+{{#each headerParams}}
+{{#if required}}
+	headers["{{originalName}}"] = fmt.Sprint({{name}})
 {{else}}
-	var result {{responseType}}
-	err := api.transport.Execute(ctx, request{
+	if {{name}} != nil { headers["{{originalName}}"] = fmt.Sprint(*{{name}}) }
+{{/if}}
+{{/each}}
+{{/if}}
+	req := request{
 		Method: "{{httpMethod}}", Path: reqPath,
-{{#if queryType}}		Query: q,{{/if}}
-{{#if requestBody}}		Body: body,{{/if}}
-	}, &result)
-	if err != nil { return nil, err }
+{{#if hasQueryParams}}		Query: query,{{/if}}
+{{#if requestBody}}		Body: body, ContentType: "{{requestBody.contentType}}",{{/if}}
+{{#if hasHeaderParams}}		Headers: headers,{{/if}}
+	}
+{{#if (eq responseType "void")}}
+	return api.transport.Execute(ctx, req, nil)
+{{else}}
+	var result {{goResponseType}}
+	if err := api.transport.Execute(ctx, req, &result); err != nil { return nil, err }
 	return &result, nil
 {{/if}}
 }

package/templates/go/go-mod.hbs

@@ -1,6 +1,3 @@
-module {{packageName}}
+module {{moduleName}}
 
 go 1.21
-
-require (
-)

package/templates/go/readme.hbs

@@ -1,8 +1,8 @@
 # {{title}} Go SDK
 
-[![Go Reference](https://pkg.go.dev/badge/{{packageName}}.svg)](https://pkg.go.dev/{{packageName}})
+{{#if description}}{{description}}{{else}}Go client for the {{title}} API.{{/if}}
 
-The official Go SDK for {{#if description}}{{description}}{{else}}the {{title}} API{{/if}}.
+> Generated by Tesseract. Generated source files should not be edited manually.
 
 ## Installation
 
@@ -10,57 +10,60 @@ The official Go SDK for {{#if description}}{{description}}{{else}}the {{title}}
 go get {{packageName}}
 ```
 
-## Quick Start
+## Quick start
 
 ```go
 package main
 
 import (
     "context"
-    "fmt"
-    "log"
+    "time"
 
     "{{packageName}}"
 )
 
 func main() {
-    client := {{pkgName}}.NewClient({{pkgName}}.DefaultClientConfig(){{#each securitySchemes}}{{#if (eq type "apiKey")}}
-        {{pascalCase configKey}}: "your-api-key",{{/if}}{{#if (and (eq type "http") (eq scheme "bearer"))}}
-        {{pascalCase configKey}}: "your-bearer-token",{{/if}}
-{{/each}}
+    client := {{pkgName}}.NewClient(
+        {{pkgName}}.WithTimeout(15*time.Second),
     )
 
     ctx := context.Background()
-{{#each groups}}
-{{#with operations.[0]}}
-    // {{../interfaceName}}.{{name}} example
-    result, err := client.{{pascalCase ../name}}.{{pascalCase name}}(ctx{{#each ../pathParams}}, "{{this}}"{{/each}}{{#if requestBody}}, {{requestBody.type}}{}{{/if}})
-    if err != nil {
-        log.Fatal(err)
-    }
-    fmt.Printf("%+v\n", result)
-{{/with}}
-{{/each}}
+    _ = ctx
+{{#if groups.length}}
+    _ = client.{{pascalCase groups.[0].name}}
+{{/if}}
 }
 ```
 
-## API Reference
+## Configuration and reliability
+
+The client is safe for concurrent use. Requests use contexts for cancellation, bounded timeouts, exponential-backoff retries, `Retry-After` handling, default headers, and structured `SDKError` values. Unsafe requests are not retried unless an idempotency key is present or unsafe retries are explicitly enabled.
+
+```go
+client := {{pkgName}}.NewClient(
+    {{pkgName}}.WithTimeout(30*time.Second),
+    {{pkgName}}.WithMaxRetries(3),
+    {{pkgName}}.WithDefaultHeader("X-Application", "my-service"),
+)
+```
+
+## Documentation
+
+- [Documentation index](./docs/README.md)
+- [Generated types](./docs/types.md)
 
 | Domain | Description |
-|--------|-------------|
+|---|---|
 {{#each groups}}
-| `{{interfaceName}}` | {{#if description}}{{description}}{{else}}{{name}} operations{{/if}} |
+| [{{interfaceName}}](./docs/domains/{{fileName}}.md) | {{#if description}}{{description}}{{else}}{{name}} operations{{/if}} |
 {{/each}}
 
-## Error Handling
-
-All methods return an `error` as the second return value. Use `errors.As` to inspect SDK-specific errors:
+## Error handling
 
 ```go
-var sdkErr *SDKError
+var sdkErr *{{pkgName}}.SDKError
 if errors.As(err, &sdkErr) {
-    fmt.Printf("Status: %d, Code: %s, RequestID: %s\n",
-        sdkErr.Status, sdkErr.Code, sdkErr.RequestID)
+    log.Printf("status=%d code=%s request=%s", sdkErr.Status, sdkErr.Code, sdkErr.RequestID)
 }
 ```
 
@@ -70,4 +73,4 @@ if errors.As(err, &sdkErr) {
 
 ## License
 
-{{#if license}}{{license}}{{else}}MIT{{/if}}
+MIT