// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

package keycard

import (

"context"

"net/http"

"os"

"slices"

"strings"

"github.com/keycardai/keycard-go/internal/requestconfig"

"github.com/keycardai/keycard-go/option"

)

// Client creates a struct with services and top level methods that help with

// interacting with the keycard-api API. You should not instantiate this client

// directly, and instead use the [NewClient] method instead.

type Client struct {

Options []option.RequestOption

Zones ZoneService

Organizations OrganizationService

Invitations InvitationService

// Per-user Policy Bundle resource. Allows clients (typically the Keycard CLI) to

// GET, PUT, and DELETE the effective Policy Set for the calling user on a zone.

// The bundle is encoded with a content-negotiated codec (currently only

// `application/vnd.keycard.policy-bundle.v1+tar+gzip`).

//

// ## Archive layout

//

// The bundle is a gzip-compressed tar archive with this logical layout:

//

// | Entry | Required on PUT | Notes |

// | ---------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

// | `manifest.json` | **Yes** | See `PolicyBundleManifest`. The only source of the authoritative `schema.version`. |

// | `schema.cedarschema` | No | Convenience snapshot of the Cedar schema. **Ignored on PUT** — the server validates policies against its own attested schema for `manifest.schema.version`. **Always present on GET.** |

// | `policies/<public_id>.cedar` | — | One Cedar policy per file; the filename stem is the policy's public ID. |

//

// Decode rules: duplicate entries and unrecognized/nested entries are rejected

// (`bundle_invalid`). On PUT the manifest's `sha` fields and `policies[]` list are

// advisory — the server recomputes every digest from the archived bytes and

// derives the policy set from the `policies/` files. On GET every digest is

// authoritative.

PolicyBundle PolicyBundleService

}

// DefaultClientOptions read from the environment (KEYCARD_API_API_KEY,

// KEYCARD_API_CLIENT_ID, KEYCARD_API_CLIENT_SECRET, KEYCARD_API_BASE_URL). This

// should be used to initialize new clients.

func DefaultClientOptions() []option.RequestOption {

defaults := []option.RequestOption{option.WithHTTPClient(defaultHTTPClient()), option.WithEnvironmentProduction()}

if o, ok := os.LookupEnv("KEYCARD_API_BASE_URL"); ok {

defaults = append(defaults, option.WithBaseURL(o))

}

if o, ok := os.LookupEnv("KEYCARD_API_API_KEY"); ok {

defaults = append(defaults, option.WithAPIKey(o))

}

if o, ok := os.LookupEnv("KEYCARD_API_CLIENT_ID"); ok {

defaults = append(defaults, option.WithClientID(o))

}

if o, ok := os.LookupEnv("KEYCARD_API_CLIENT_SECRET"); ok {

defaults = append(defaults, option.WithClientSecret(o))

}

if o, ok := os.LookupEnv("KEYCARD_API_CUSTOM_HEADERS"); ok {

for _, line := range strings.Split(o, "\n") {

colon := strings.Index(line, ":")

if colon >= 0 {

defaults = append(defaults, option.WithHeader(strings.TrimSpace(line[:colon]), strings.TrimSpace(line[colon+1:])))

}

}

}

return defaults

}

// NewClient generates a new client with the default option read from the

// environment (KEYCARD_API_API_KEY, KEYCARD_API_CLIENT_ID,

// KEYCARD_API_CLIENT_SECRET, KEYCARD_API_BASE_URL). The option passed in as

// arguments are applied after these default arguments, and all option will be

// passed down to the services and requests that this client makes.

func NewClient(opts ...option.RequestOption) (r Client) {

opts = append(DefaultClientOptions(), opts...)

r = Client{Options: opts}

r.Zones = NewZoneService(opts...)

r.Organizations = NewOrganizationService(opts...)

r.Invitations = NewInvitationService(opts...)

r.PolicyBundle = NewPolicyBundleService(opts...)

return

}

// Execute makes a request with the given context, method, URL, request params,

// response, and request options. This is useful for hitting undocumented endpoints

// while retaining the base URL, auth, retries, and other options from the client.

//

// If a byte slice or an [io.Reader] is supplied to params, it will be used as-is

// for the request body.

//

// The params is by default serialized into the body using [encoding/json]. If your

// type implements a MarshalJSON function, it will be used instead to serialize the

// request. If a URLQuery method is implemented, the returned [url.Values] will be

// used as query strings to the url.

//

// If your params struct uses [param.Field], you must provide either [MarshalJSON],

// [URLQuery], and/or [MarshalForm] functions. It is undefined behavior to use a

// struct uses [param.Field] without specifying how it is serialized.

//

// Any "…Params" object defined in this library can be used as the request

// argument. Note that 'path' arguments will not be forwarded into the url.

//

// The response body will be deserialized into the res variable, depending on its

// type:

//

// - A pointer to a [*http.Response] is populated by the raw response.

// - A pointer to a byte array will be populated with the contents of the request

// body.

// - A pointer to any other type uses this library's default JSON decoding, which

// respects UnmarshalJSON if it is defined on the type.

// - A nil value will not read the response body.

//

// For even greater flexibility, see [option.WithResponseInto] and

// [option.WithResponseBodyInto].

func (r *Client) Execute(ctx context.Context, method string, path string, params any, res any, opts ...option.RequestOption) error {

opts = slices.Concat(r.Options, opts)

return requestconfig.ExecuteNewRequest(ctx, method, path, params, res, opts...)

}

// Get makes a GET request with the given URL, params, and optionally deserializes

// to a response. See [Execute] documentation on the params and response.

func (r *Client) Get(ctx context.Context, path string, params any, res any, opts ...option.RequestOption) error {

return r.Execute(ctx, http.MethodGet, path, params, res, opts...)

}

// Post makes a POST request with the given URL, params, and optionally

// deserializes to a response. See [Execute] documentation on the params and

// response.

func (r *Client) Post(ctx context.Context, path string, params any, res any, opts ...option.RequestOption) error {

return r.Execute(ctx, http.MethodPost, path, params, res, opts...)

}

// Put makes a PUT request with the given URL, params, and optionally deserializes

// to a response. See [Execute] documentation on the params and response.

func (r *Client) Put(ctx context.Context, path string, params any, res any, opts ...option.RequestOption) error {

return r.Execute(ctx, http.MethodPut, path, params, res, opts...)

}

// Patch makes a PATCH request with the given URL, params, and optionally

// deserializes to a response. See [Execute] documentation on the params and

// response.

func (r *Client) Patch(ctx context.Context, path string, params any, res any, opts ...option.RequestOption) error {

return r.Execute(ctx, http.MethodPatch, path, params, res, opts...)

}

// Delete makes a DELETE request with the given URL, params, and optionally

// deserializes to a response. See [Execute] documentation on the params and

// response.

func (r *Client) Delete(ctx context.Context, path string, params any, res any, opts ...option.RequestOption) error {

return r.Execute(ctx, http.MethodDelete, path, params, res, opts...)

}