apikey.go

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

package kernel

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"net/url"
	"slices"
	"time"

	"github.com/kernel/kernel-go-sdk/internal/apijson"
	"github.com/kernel/kernel-go-sdk/internal/apiquery"
	"github.com/kernel/kernel-go-sdk/internal/requestconfig"
	"github.com/kernel/kernel-go-sdk/option"
	"github.com/kernel/kernel-go-sdk/packages/pagination"
	"github.com/kernel/kernel-go-sdk/packages/param"
	"github.com/kernel/kernel-go-sdk/packages/respjson"
)

// Create and manage API keys for organization and project-scoped access.
//
// APIKeyService contains methods and other services that help with interacting
// with the kernel API.
//
// Note, unlike clients, this service does not read variables from the environment
// automatically. You should not instantiate this service directly, and instead use
// the [NewAPIKeyService] method instead.
type APIKeyService struct {
	Options []option.RequestOption
}

// NewAPIKeyService generates a new service that applies the given options to each
// request. These options are applied after the parent client's options (if there
// is one), and before any request-specific options.
func NewAPIKeyService(opts ...option.RequestOption) (r APIKeyService) {
	r = APIKeyService{}
	r.Options = opts
	return
}

// Create a new API key. API keys may be scoped by project and may include a
// policy.
func (r *APIKeyService) New(ctx context.Context, body APIKeyNewParams, opts ...option.RequestOption) (res *CreatedAPIKey, err error) {
	opts = slices.Concat(r.Options, opts)
	path := "org/api_keys"
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
	return res, err
}

// Retrieve an API key by ID for the authenticated organization. API keys are
// masked.
func (r *APIKeyService) Get(ctx context.Context, id string, query APIKeyGetParams, opts ...option.RequestOption) (res *APIKey, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("org/api_keys/%s", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...)
	return res, err
}

// Update an API key's name.
func (r *APIKeyService) Update(ctx context.Context, id string, body APIKeyUpdateParams, opts ...option.RequestOption) (res *APIKey, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("org/api_keys/%s", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPatch, path, body, &res, opts...)
	return res, err
}

// List API keys for the authenticated organization. API keys are masked.
func (r *APIKeyService) List(ctx context.Context, query APIKeyListParams, opts ...option.RequestOption) (res *pagination.OffsetPagination[APIKey], err error) {
	var raw *http.Response
	opts = slices.Concat(r.Options, opts)
	opts = append([]option.RequestOption{option.WithResponseInto(&raw)}, opts...)
	path := "org/api_keys"
	cfg, err := requestconfig.NewRequestConfig(ctx, http.MethodGet, path, query, &res, opts...)
	if err != nil {
		return nil, err
	}
	err = cfg.Execute()
	if err != nil {
		return nil, err
	}
	res.SetPageConfig(cfg, raw)
	return res, nil
}

// List API keys for the authenticated organization. API keys are masked.
func (r *APIKeyService) ListAutoPaging(ctx context.Context, query APIKeyListParams, opts ...option.RequestOption) *pagination.OffsetPaginationAutoPager[APIKey] {
	return pagination.NewOffsetPaginationAutoPager(r.List(ctx, query, opts...))
}

// Delete an API key. A key cannot delete itself; use a different key to delete
// this one.
func (r *APIKeyService) Delete(ctx context.Context, id string, opts ...option.RequestOption) (err error) {
	opts = slices.Concat(r.Options, opts)
	opts = append([]option.RequestOption{option.WithHeader("Accept", "*/*")}, opts...)
	if id == "" {
		err = errors.New("missing required id parameter")
		return err
	}
	path := fmt.Sprintf("org/api_keys/%s", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodDelete, path, nil, nil, opts...)
	return err
}

// Rotate an API key. Issues a new key that copies the name and project of the
// rotated key, and schedules the rotated key to expire after a grace period so
// in-flight callers can swap over. The new plaintext key is returned once.
func (r *APIKeyService) Rotate(ctx context.Context, id string, body APIKeyRotateParams, opts ...option.RequestOption) (res *CreatedAPIKey, err error) {
	opts = slices.Concat(r.Options, opts)
	if id == "" {
		err = errors.New("missing required id parameter")
		return nil, err
	}
	path := fmt.Sprintf("org/api_keys/%s/rotate", id)
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
	return res, err
}

type APIKey struct {
	// Unique API key identifier
	ID string `json:"id" api:"required"`
	// When the API key was created
	CreatedAt time.Time       `json:"created_at" api:"required" format:"date-time"`
	CreatedBy APIKeyCreatedBy `json:"created_by" api:"required"`
	// When the API key was deleted (soft-deleted). Null for keys that have not been
	// deleted.
	DeletedAt time.Time `json:"deleted_at" api:"required" format:"date-time"`
	// When the API key expires
	ExpiresAt time.Time `json:"expires_at" api:"required" format:"date-time"`
	// When the API key last authenticated a request, accurate to within about 20
	// minutes. Null if the key has not been used since last-use tracking began.
	LastUsedAt time.Time `json:"last_used_at" api:"required" format:"date-time"`
	// Masked version of the API key
	MaskedKey string `json:"masked_key" api:"required"`
	// Label for the API key. API keys are not addressable by name; use the ID or key
	// identifier for stable references.
	Name string `json:"name" api:"required"`
	// Project identifier for project-scoped API keys. Null means org-wide.
	ProjectID string `json:"project_id" api:"required"`
	// Project name for project-scoped API keys. Null means the key is org-wide or the
	// project name is unavailable.
	ProjectName string `json:"project_name" api:"required"`
	// Permissions granted to a scoped API key. Absent for an ordinary key, which keeps
	// unrestricted access within its organization or project.
	Policy APIKeyPolicy `json:"policy" api:"nullable"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ID          respjson.Field
		CreatedAt   respjson.Field
		CreatedBy   respjson.Field
		DeletedAt   respjson.Field
		ExpiresAt   respjson.Field
		LastUsedAt  respjson.Field
		MaskedKey   respjson.Field
		Name        respjson.Field
		ProjectID   respjson.Field
		ProjectName respjson.Field
		Policy      respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r APIKey) RawJSON() string { return r.JSON.raw }
func (r *APIKey) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type APIKeyCreatedBy struct {
	// Kernel user ID of the creator.
	ID string `json:"id" api:"required"`
	// Email address of the creator.
	Email string `json:"email" api:"required" format:"email"`
	// Display name of the creator, if available.
	Name string `json:"name" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		ID          respjson.Field
		Email       respjson.Field
		Name        respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r APIKeyCreatedBy) RawJSON() string { return r.JSON.raw }
func (r *APIKeyCreatedBy) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Permissions granted to a scoped API key. Absent for an ordinary key, which keeps
// unrestricted access within its organization or project.
type APIKeyPolicy struct {
	// Allow statements. Every action and resource not listed is denied.
	Statements []APIKeyPolicyStatement `json:"statements" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Statements  respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r APIKeyPolicy) RawJSON() string { return r.JSON.raw }
func (r *APIKeyPolicy) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type APIKeyPolicyStatement struct {
	// Permitted action, such as browsers:use or vaults:read.
	Action string `json:"action" api:"required"`
	// Resource the action applies to, in the format projects/{project_id}/{kind}/{id}.
	// Wildcards are supported.
	Resource string `json:"resource" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Action      respjson.Field
		Resource    respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r APIKeyPolicyStatement) RawJSON() string { return r.JSON.raw }
func (r *APIKeyPolicyStatement) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// API key returned immediately after creation. Includes the plaintext key once.
type CreatedAPIKey struct {
	// Plaintext API key. Only returned once when the key is created.
	Key string `json:"key" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Key         respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
	APIKey
}

// Returns the unmodified JSON received from the API
func (r CreatedAPIKey) RawJSON() string { return r.JSON.raw }
func (r *CreatedAPIKey) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type APIKeyNewParams struct {
	// Label for the API key (1-255 characters). API keys are not addressable by name.
	Name string `json:"name" api:"required"`
	// Number of days until expiry, up to 3650. Use null for never. Cannot be combined
	// with expires_at.
	DaysToExpire param.Opt[int64] `json:"days_to_expire,omitzero"`
	// Exact expiry time. Must be in the future and no later than the issuing
	// credential's own expiry. Cannot be combined with days_to_expire.
	ExpiresAt param.Opt[time.Time] `json:"expires_at,omitzero" format:"date-time"`
	// Unique project identifier
	ProjectID param.Opt[string] `json:"project_id,omitzero"`
	// Issue a scoped key that may only perform the listed actions on the listed
	// resources.
	Policy APIKeyNewParamsPolicy `json:"policy,omitzero"`
	paramObj
}

func (r APIKeyNewParams) MarshalJSON() (data []byte, err error) {
	type shadow APIKeyNewParams
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *APIKeyNewParams) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// Issue a scoped key that may only perform the listed actions on the listed
// resources.
//
// The property Statements is required.
type APIKeyNewParamsPolicy struct {
	// Allow statements. Every action and resource not listed is denied.
	Statements []APIKeyNewParamsPolicyStatement `json:"statements,omitzero" api:"required"`
	paramObj
}

func (r APIKeyNewParamsPolicy) MarshalJSON() (data []byte, err error) {
	type shadow APIKeyNewParamsPolicy
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *APIKeyNewParamsPolicy) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// The properties Action, Resource are required.
type APIKeyNewParamsPolicyStatement struct {
	// Permitted action, such as browsers:use or vaults:read.
	Action string `json:"action" api:"required"`
	// Resource the action applies to, in the format projects/{project_id}/{kind}/{id}.
	// Wildcards are supported.
	Resource string `json:"resource" api:"required"`
	paramObj
}

func (r APIKeyNewParamsPolicyStatement) MarshalJSON() (data []byte, err error) {
	type shadow APIKeyNewParamsPolicyStatement
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *APIKeyNewParamsPolicyStatement) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type APIKeyGetParams struct {
	// When true, return the API key even if it has been deleted (soft-deleted), for
	// audit purposes. Defaults to false, which returns 404 for a deleted key.
	IncludeDeleted param.Opt[bool] `query:"include_deleted,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [APIKeyGetParams]'s query parameters as `url.Values`.
func (r APIKeyGetParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

type APIKeyUpdateParams struct {
	// New API key name
	Name string `json:"name" api:"required"`
	paramObj
}

func (r APIKeyUpdateParams) MarshalJSON() (data []byte, err error) {
	type shadow APIKeyUpdateParams
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *APIKeyUpdateParams) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type APIKeyListParams struct {
	// Deprecated: use status=all instead. When true, include deleted (soft-deleted)
	// API keys in the results for audit purposes.
	IncludeDeleted param.Opt[bool] `query:"include_deleted,omitzero" json:"-"`
	// Maximum number of results to return
	Limit param.Opt[int64] `query:"limit,omitzero" json:"-"`
	// Exact-match filter on API key name using the database collation. In production,
	// matching is case- and accent-insensitive. Names are not required to be unique,
	// so multiple keys may match. When status=all or include_deleted=true is set,
	// soft-deleted keys with the same name may also match.
	Name param.Opt[string] `query:"name,omitzero" json:"-"`
	// Number of results to skip
	Offset param.Opt[int64] `query:"offset,omitzero" json:"-"`
	// Case-insensitive substring match against API key name, creator, and project. API
	// key identifiers and masked keys match by exact value or prefix.
	Query param.Opt[string] `query:"query,omitzero" json:"-"`
	// Field to sort API keys by. Keys with no expiry or no recorded use sort last for
	// expires_at and last_used_at in either direction.
	//
	// Any of "created_at", "name", "expires_at", "last_used_at".
	SortBy APIKeyListParamsSortBy `query:"sort_by,omitzero" json:"-"`
	// Sort direction for API keys.
	//
	// Any of "asc", "desc".
	SortDirection APIKeyListParamsSortDirection `query:"sort_direction,omitzero" json:"-"`
	// Filter API keys by status. "active" returns keys that are not deleted (default;
	// expired-but-not-deleted keys are still included), "deleted" returns only
	// soft-deleted keys, "all" returns both.
	//
	// Any of "active", "deleted", "all".
	Status APIKeyListParamsStatus `query:"status,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [APIKeyListParams]'s query parameters as `url.Values`.
func (r APIKeyListParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

// Field to sort API keys by. Keys with no expiry or no recorded use sort last for
// expires_at and last_used_at in either direction.
type APIKeyListParamsSortBy string

const (
	APIKeyListParamsSortByCreatedAt  APIKeyListParamsSortBy = "created_at"
	APIKeyListParamsSortByName       APIKeyListParamsSortBy = "name"
	APIKeyListParamsSortByExpiresAt  APIKeyListParamsSortBy = "expires_at"
	APIKeyListParamsSortByLastUsedAt APIKeyListParamsSortBy = "last_used_at"
)

// Sort direction for API keys.
type APIKeyListParamsSortDirection string

const (
	APIKeyListParamsSortDirectionAsc  APIKeyListParamsSortDirection = "asc"
	APIKeyListParamsSortDirectionDesc APIKeyListParamsSortDirection = "desc"
)

// Filter API keys by status. "active" returns keys that are not deleted (default;
// expired-but-not-deleted keys are still included), "deleted" returns only
// soft-deleted keys, "all" returns both.
type APIKeyListParamsStatus string

const (
	APIKeyListParamsStatusActive  APIKeyListParamsStatus = "active"
	APIKeyListParamsStatusDeleted APIKeyListParamsStatus = "deleted"
	APIKeyListParamsStatusAll     APIKeyListParamsStatus = "all"
)

type APIKeyRotateParams struct {
	// Lifetime in days for the new key, up to 3650. Omit to reuse the rotated key's
	// original lifetime, or never-expires if it had none.
	DaysToExpire param.Opt[int64] `json:"days_to_expire,omitzero"`
	// Grace period in days before the rotated key expires. Use 0 to expire it
	// immediately. Omit for the default grace period of 7 days.
	ExpireInDays param.Opt[int64] `json:"expire_in_days,omitzero"`
	paramObj
}

func (r APIKeyRotateParams) MarshalJSON() (data []byte, err error) {
	type shadow APIKeyRotateParams
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *APIKeyRotateParams) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}