diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock new file mode 100644 index 0000000..a222c05 --- /dev/null +++ b/.github/workflows/actions.lock @@ -0,0 +1,86 @@ +# This file is machine-generated by `gh actions-lock`. +# Do not edit by hand; run `gh actions-lock` to update. +# Docs: https://gh.io/actions-lockfile +version: 'v0.0.3' +workflows: + '.github/workflows/ci.yml': + - 'actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5' + - 'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd' + - 'actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd' + - 'actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff' + - 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' + '.github/workflows/release-please.yml': + - 'actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547' + - 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' + - 'pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1' + '.github/workflows/semgrep.yml': [] + '.github/workflows/stlc-promote.yml': + - 'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd' + - 'actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547' + '.github/workflows/stlc-sync.yml': + - 'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd' + '.github/workflows/update-cli-coverage.yml': + - 'actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5' + - 'actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547' + - 'actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093' + - 'actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16' + - 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020' + - 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02' + - 'kernel/security-workflows@4144994f1d6977e07ef5a5832599ee4faaae9550' + '.github/workflows/vuln-remediation.yml': [] +dependencies: + 'actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5': + ref: 'v4.3.1' + commit: 'sha1-34e114876b0b11c390a56381ad16ebd13914f8d5' + owner_id: 44036562 + repo_id: 197814629 + 'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd': + ref: 'v6.0.2' + commit: 'sha1-de0fac2e4500dabe0009e67214ff5f5447ce83dd' + owner_id: 44036562 + repo_id: 197814629 + 'actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547': + ref: 'v1.12.0' + commit: 'sha1-d72941d797fd3113feb6b93fd0dec494b13a2547' + owner_id: 44036562 + repo_id: 642580244 + 'actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093': + ref: 'v4.3.0' + commit: 'sha1-d3f86a106a0bac45b974a628896c90dbdf5c8093' + owner_id: 44036562 + repo_id: 192626254 + 'actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd': + ref: 'v8.0.0' + commit: 'sha1-ed597411d8f924073f98dfc5c65a23a2325f34cd' + owner_id: 44036562 + repo_id: 205262760 + 'actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff': + ref: 'v5.6.0' + commit: 'sha1-40f1582b2485089dde7abd97c1529aa768e1baff' + owner_id: 44036562 + repo_id: 192624594 + 'actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16': + ref: 'v6.5.0' + commit: 'sha1-924ae3a1cded613372ab5595356fb5720e22ba16' + owner_id: 44036562 + repo_id: 192624594 + 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020': + ref: 'v4.4.0' + commit: 'sha1-49933ea5288caeca8642d1e84afbd3f7d6820020' + owner_id: 44036562 + repo_id: 189476904 + 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02': + ref: 'v4.6.2' + commit: 'sha1-ea165f8d65b6e75b540449e92b4886f43607fa02' + owner_id: 44036562 + repo_id: 192625955 + 'kernel/security-workflows@4144994f1d6977e07ef5a5832599ee4faaae9550': + ref: 'main' + commit: 'sha1-4144994f1d6977e07ef5a5832599ee4faaae9550' + owner_id: 194616459 + repo_id: 1207196574 + 'pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1': + ref: 'v4.3.0' + commit: 'sha1-b906affcce14559ad1aafd4ab0e942779e9f58b1' + owner_id: 21320719 + repo_id: 262289747 diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index fca9f0c..0568727 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -41,7 +41,7 @@ jobs: node-version: '22' - name: Set up pnpm - uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4 + uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4.3.0 with: version: '9.11.0' run_install: false diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 2b1627b..023707a 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.148.0" + ".": "0.149.0" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index 4731cdc..a4bdf76 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1 +1 @@ -configured_endpoints: 179 +configured_endpoints: 189 diff --git a/CHANGELOG.md b/CHANGELOG.md index 8f28796..516ce51 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## [0.149.0](https://github.com/kernel/kernel-go-sdk/compare/v0.148.0...v0.149.0) (2026-11-16) + + +### Features + +* Add reports API and report type discovery ([77a104f](https://github.com/kernel/kernel-go-sdk/commit/77a104ffd9c3af0e5b0875e0b5a0fe20c47eaacf)) +* Add tasks API: create, list, get, and link browsers ([63f6f0e](https://github.com/kernel/kernel-go-sdk/commit/63f6f0e14f7cbece270e006b2d3c873204c8d488)) +* Let vault item events be read after the item or vault is deleted ([cd6b59f](https://github.com/kernel/kernel-go-sdk/commit/cd6b59f4bd6780220c123a2813e4b20ac0f9c072)) + ## [0.148.0](https://github.com/kernel/kernel-go-sdk/compare/v0.147.0...v0.148.0) (2026-11-12) diff --git a/README.md b/README.md index 1d628fa..e08e1f9 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Or to pin the version: ```sh -go get -u 'github.com/kernel/kernel-go-sdk@v0.148.0' +go get -u 'github.com/kernel/kernel-go-sdk@v0.149.0' ``` diff --git a/api.md b/api.md index eccd410..f262a01 100644 --- a/api.md +++ b/api.md @@ -418,6 +418,59 @@ Methods: - client.Profiles.Delete(ctx context.Context, idOrName string) error - client.Profiles.Download(ctx context.Context, idOrName string, query kernel.ProfileDownloadParams) (\*http.Response, error) +# Tasks + +Params Types: + +- kernel.TaskMetadata + +Response Types: + +- kernel.Task +- kernel.TaskMetadata + +Methods: + +- client.Tasks.New(ctx context.Context, body kernel.TaskNewParams) (\*kernel.Task, error) +- client.Tasks.Get(ctx context.Context, id string) (\*kernel.Task, error) +- client.Tasks.List(ctx context.Context, query kernel.TaskListParams) (\*pagination.OffsetPagination[kernel.Task], error) +- client.Tasks.LinkBrowsers(ctx context.Context, id string, body kernel.TaskLinkBrowsersParams) (\*kernel.Task, error) + +# Reports + +Response Types: + +- kernel.Report + +Methods: + +- client.Reports.New(ctx context.Context, body kernel.ReportNewParams) (\*kernel.Report, error) +- client.Reports.Get(ctx context.Context, id string) (\*kernel.Report, error) +- client.Reports.List(ctx context.Context, query kernel.ReportListParams) (\*pagination.OffsetPagination[kernel.Report], error) + +# ReportTypes + +Response Types: + +- kernel.ReportType +- kernel.ReportTypeSummary +- kernel.ReportTypeVersionSummary + +Methods: + +- client.ReportTypes.Get(ctx context.Context, type\_ string) (\*kernel.ReportType, error) +- client.ReportTypes.List(ctx context.Context, query kernel.ReportTypeListParams) (\*pagination.OffsetPagination[kernel.ReportTypeSummary], error) + +## Versions + +Response Types: + +- kernel.ReportTypeVersion + +Methods: + +- client.ReportTypes.Versions.Get(ctx context.Context, version int64, query kernel.ReportTypeVersionGetParams) (\*kernel.ReportTypeVersion, error) + # Auth ## Context diff --git a/client.go b/client.go index b3a0f98..be88acd 100644 --- a/client.go +++ b/client.go @@ -31,9 +31,15 @@ type Client struct { ConfigRegistry ConfigRegistryService Browsers BrowserService // Create, list, retrieve, and delete browser profiles. - Profiles ProfileService - Auth AuthService - Telemetry TelemetryService + Profiles ProfileService + // Define tasks that agents work toward and link the browsers they use. + Tasks TaskService + // Discover report types and submit typed reports against tasks. + Reports ReportService + // Discover report types and submit typed reports against tasks. + ReportTypes ReportTypeService + Auth AuthService + Telemetry TelemetryService // Create and manage proxy configurations for routing browser traffic. Proxies ProxyService // Create and manage proxy configurations for routing browser traffic. @@ -100,6 +106,9 @@ func NewClient(opts ...option.RequestOption) (r Client) { r.ConfigRegistry = NewConfigRegistryService(opts...) r.Browsers = NewBrowserService(opts...) r.Profiles = NewProfileService(opts...) + r.Tasks = NewTaskService(opts...) + r.Reports = NewReportService(opts...) + r.ReportTypes = NewReportTypeService(opts...) r.Auth = NewAuthService(opts...) r.Telemetry = NewTelemetryService(opts...) r.Proxies = NewProxyService(opts...) diff --git a/internal/version.go b/internal/version.go index 5d2eeda..207cef7 100644 --- a/internal/version.go +++ b/internal/version.go @@ -2,4 +2,4 @@ package internal -const PackageVersion = "0.148.0" // x-release-please-version +const PackageVersion = "0.149.0" // x-release-please-version diff --git a/report.go b/report.go new file mode 100644 index 0000000..894fd85 --- /dev/null +++ b/report.go @@ -0,0 +1,177 @@ +// 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" +) + +// Discover report types and submit typed reports against tasks. +// +// ReportService 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 [NewReportService] method instead. +type ReportService struct { + Options []option.RequestOption +} + +// NewReportService 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 NewReportService(opts ...option.RequestOption) (r ReportService) { + r = ReportService{} + r.Options = opts + return +} + +// Submit a typed report against a task. The data is validated against the report +// type's schema; a validation failure returns 400 with one detail per invalid +// field. A task can have at most 500 reports. +func (r *ReportService) New(ctx context.Context, body ReportNewParams, opts ...option.RequestOption) (res *Report, err error) { + opts = slices.Concat(r.Options, opts) + path := "reports" + err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...) + return res, err +} + +// Retrieve a report. +func (r *ReportService) Get(ctx context.Context, id string, opts ...option.RequestOption) (res *Report, err error) { + opts = slices.Concat(r.Options, opts) + if id == "" { + err = errors.New("missing required id parameter") + return nil, err + } + path := fmt.Sprintf("reports/%s", id) + err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...) + return res, err +} + +// List a task's reports in the order they were submitted, oldest first. +func (r *ReportService) List(ctx context.Context, query ReportListParams, opts ...option.RequestOption) (res *pagination.OffsetPagination[Report], err error) { + var raw *http.Response + opts = slices.Concat(r.Options, opts) + opts = append([]option.RequestOption{option.WithResponseInto(&raw)}, opts...) + path := "reports" + 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 a task's reports in the order they were submitted, oldest first. +func (r *ReportService) ListAutoPaging(ctx context.Context, query ReportListParams, opts ...option.RequestOption) *pagination.OffsetPaginationAutoPager[Report] { + return pagination.NewOffsetPaginationAutoPager(r.List(ctx, query, opts...)) +} + +// A typed, schema-validated report an agent submitted against a task. Reports are +// immutable. +type Report struct { + // Unique identifier for the report + ID string `json:"id" api:"required"` + // When the report was submitted + CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"` + // Report data, matching the report type's schema + Data map[string]any `json:"data" api:"required"` + // When the reported event happened + OccurredAt time.Time `json:"occurred_at" api:"required" format:"date-time"` + // Version of the report type's schema that data was validated against + SchemaVersion int64 `json:"schema_version" api:"required"` + // ID of the task the report belongs to + TaskID string `json:"task_id" api:"required"` + // Report type name + Type string `json:"type" api:"required"` + // ID of the browser the report was observed in, if any + SessionID string `json:"session_id" api:"nullable"` + // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. + JSON struct { + ID respjson.Field + CreatedAt respjson.Field + Data respjson.Field + OccurredAt respjson.Field + SchemaVersion respjson.Field + TaskID respjson.Field + Type respjson.Field + SessionID respjson.Field + ExtraFields map[string]respjson.Field + raw string + } `json:"-"` +} + +// Returns the unmodified JSON received from the API +func (r Report) RawJSON() string { return r.JSON.raw } +func (r *Report) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +type ReportNewParams struct { + // Report data. It must match the schema of the report type's version and encode to + // at most 16 KB of JSON. + Data map[string]any `json:"data,omitzero" api:"required"` + // ID of the task to report against. + TaskID string `json:"task_id" api:"required"` + // Report type name. List report types to see the available types and their + // schemas. + Type string `json:"type" api:"required"` + // When the reported event happened. Defaults to the time the report is submitted. + // Must be no more than 5 minutes in the future or 30 days in the past. + OccurredAt param.Opt[time.Time] `json:"occurred_at,omitzero" format:"date-time"` + // Version of the report type's schema to validate data against. Defaults to the + // type's latest version, which the response returns. + SchemaVersion param.Opt[int64] `json:"schema_version,omitzero"` + // ID of the browser the report was observed in. It must belong to the task's + // project; deleted browsers are accepted. The browser is linked to the task if it + // is not already. + SessionID param.Opt[string] `json:"session_id,omitzero"` + paramObj +} + +func (r ReportNewParams) MarshalJSON() (data []byte, err error) { + type shadow ReportNewParams + return param.MarshalObject(r, (*shadow)(&r)) +} +func (r *ReportNewParams) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +type ReportListParams struct { + // Task whose reports to list. + TaskID string `query:"task_id" api:"required" json:"-"` + // Limit the number of reports to return. + Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` + // Offset the number of reports to return. + Offset param.Opt[int64] `query:"offset,omitzero" json:"-"` + // Only return reports of this type. + Type param.Opt[string] `query:"type,omitzero" json:"-"` + paramObj +} + +// URLQuery serializes [ReportListParams]'s query parameters as `url.Values`. +func (r ReportListParams) URLQuery() (v url.Values, err error) { + return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{ + ArrayFormat: apiquery.ArrayQueryFormatComma, + NestedFormat: apiquery.NestedQueryFormatBrackets, + }) +} diff --git a/report_test.go b/report_test.go new file mode 100644 index 0000000..b1a6fd4 --- /dev/null +++ b/report_test.go @@ -0,0 +1,99 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +package kernel_test + +import ( + "context" + "errors" + "os" + "testing" + "time" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/internal/testutil" + "github.com/kernel/kernel-go-sdk/option" +) + +func TestReportNewWithOptionalParams(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := kernel.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.Reports.New(context.TODO(), kernel.ReportNewParams{ + Data: map[string]any{ + "result": "bar", + "evidence": "bar", + }, + TaskID: "x", + Type: "task.result", + OccurredAt: kernel.Time(time.Now()), + SchemaVersion: kernel.Int(1), + SessionID: kernel.String("x"), + }) + if err != nil { + var apierr *kernel.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} + +func TestReportGet(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := kernel.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.Reports.Get(context.TODO(), "id") + if err != nil { + var apierr *kernel.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} + +func TestReportListWithOptionalParams(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := kernel.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.Reports.List(context.TODO(), kernel.ReportListParams{ + TaskID: "task_id", + Limit: kernel.Int(1), + Offset: kernel.Int(0), + Type: kernel.String("type"), + }) + if err != nil { + var apierr *kernel.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} diff --git a/reporttype.go b/reporttype.go new file mode 100644 index 0000000..613df6d --- /dev/null +++ b/reporttype.go @@ -0,0 +1,182 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +package kernel + +import ( + "context" + "errors" + "fmt" + "net/http" + "net/url" + "slices" + + "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" +) + +// Discover report types and submit typed reports against tasks. +// +// ReportTypeService 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 [NewReportTypeService] method instead. +type ReportTypeService struct { + Options []option.RequestOption + // Discover report types and submit typed reports against tasks. + Versions ReportTypeVersionService +} + +// NewReportTypeService 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 NewReportTypeService(opts ...option.RequestOption) (r ReportTypeService) { + r = ReportTypeService{} + r.Options = opts + r.Versions = NewReportTypeVersionService(opts...) + return +} + +// Retrieve a report type, its versions, and the JSON Schema of its latest version. +func (r *ReportTypeService) Get(ctx context.Context, type_ string, opts ...option.RequestOption) (res *ReportType, err error) { + opts = slices.Concat(r.Options, opts) + if type_ == "" { + err = errors.New("missing required type parameter") + return nil, err + } + path := fmt.Sprintf("report_types/%s", type_) + err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...) + return res, err +} + +// List the report types agents can submit for a task. Retrieve a type for the JSON +// Schema of its data. +func (r *ReportTypeService) List(ctx context.Context, query ReportTypeListParams, opts ...option.RequestOption) (res *pagination.OffsetPagination[ReportTypeSummary], err error) { + var raw *http.Response + opts = slices.Concat(r.Options, opts) + opts = append([]option.RequestOption{option.WithResponseInto(&raw)}, opts...) + path := "report_types" + 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 the report types agents can submit for a task. Retrieve a type for the JSON +// Schema of its data. +func (r *ReportTypeService) ListAutoPaging(ctx context.Context, query ReportTypeListParams, opts ...option.RequestOption) *pagination.OffsetPaginationAutoPager[ReportTypeSummary] { + return pagination.NewOffsetPaginationAutoPager(r.List(ctx, query, opts...)) +} + +// A kind of report agents can submit against a task, with its versions and the +// JSON Schema of its latest version. A shipped version never changes; changes ship +// as new versions. +type ReportType struct { + // What the report type records and when to submit it + Description string `json:"description" api:"required"` + // Highest version that is not retired. A report submitted without a schema_version + // uses this version. It is 0 when every version is retired. + LatestVersion int64 `json:"latest_version" api:"required"` + // JSON Schema (draft 2020-12) of the latest version, which a report's data must + // match. Its field descriptions and examples describe what to send. Null when + // every version is retired. + Schema map[string]any `json:"schema" api:"required"` + // Report type name, such as task.result + Type string `json:"type" api:"required"` + // Every version of the type, oldest first, including retired versions. + Versions []ReportTypeVersionSummary `json:"versions" api:"required"` + // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. + JSON struct { + Description respjson.Field + LatestVersion respjson.Field + Schema respjson.Field + Type respjson.Field + Versions respjson.Field + ExtraFields map[string]respjson.Field + raw string + } `json:"-"` +} + +// Returns the unmodified JSON received from the API +func (r ReportType) RawJSON() string { return r.JSON.raw } +func (r *ReportType) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +// A kind of report agents can submit against a task. Retrieve the type for the +// JSON Schema of its data. +type ReportTypeSummary struct { + // What the report type records and when to submit it + Description string `json:"description" api:"required"` + // Highest version that is not retired. A report submitted without a schema_version + // uses this version. It is 0 when every version is retired. + LatestVersion int64 `json:"latest_version" api:"required"` + // Report type name, such as task.result + Type string `json:"type" api:"required"` + // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. + JSON struct { + Description respjson.Field + LatestVersion respjson.Field + Type respjson.Field + ExtraFields map[string]respjson.Field + raw string + } `json:"-"` +} + +// Returns the unmodified JSON received from the API +func (r ReportTypeSummary) RawJSON() string { return r.JSON.raw } +func (r *ReportTypeSummary) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +// One schema version of a report type, without its schema. +type ReportTypeVersionSummary struct { + // Whether the version is retired. Retired versions are no longer accepted for new + // reports; existing reports keep them. + Retired bool `json:"retired" api:"required"` + // Schema version number, starting at 1. + Version int64 `json:"version" api:"required"` + // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. + JSON struct { + Retired respjson.Field + Version respjson.Field + ExtraFields map[string]respjson.Field + raw string + } `json:"-"` +} + +// Returns the unmodified JSON received from the API +func (r ReportTypeVersionSummary) RawJSON() string { return r.JSON.raw } +func (r *ReportTypeVersionSummary) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +type ReportTypeListParams struct { + // Task the agent is finding a report type for. + TaskID string `query:"task_id" api:"required" json:"-"` + // Limit the number of report types to return. + Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` + // Offset the number of report types to return. + Offset param.Opt[int64] `query:"offset,omitzero" json:"-"` + paramObj +} + +// URLQuery serializes [ReportTypeListParams]'s query parameters as `url.Values`. +func (r ReportTypeListParams) URLQuery() (v url.Values, err error) { + return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{ + ArrayFormat: apiquery.ArrayQueryFormatComma, + NestedFormat: apiquery.NestedQueryFormatBrackets, + }) +} diff --git a/reporttype_test.go b/reporttype_test.go new file mode 100644 index 0000000..1b87035 --- /dev/null +++ b/reporttype_test.go @@ -0,0 +1,64 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +package kernel_test + +import ( + "context" + "errors" + "os" + "testing" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/internal/testutil" + "github.com/kernel/kernel-go-sdk/option" +) + +func TestReportTypeGet(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := kernel.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.ReportTypes.Get(context.TODO(), "type") + if err != nil { + var apierr *kernel.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} + +func TestReportTypeListWithOptionalParams(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := kernel.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.ReportTypes.List(context.TODO(), kernel.ReportTypeListParams{ + TaskID: "task_id", + Limit: kernel.Int(1), + Offset: kernel.Int(0), + }) + if err != nil { + var apierr *kernel.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} diff --git a/reporttypeversion.go b/reporttypeversion.go new file mode 100644 index 0000000..42b0487 --- /dev/null +++ b/reporttypeversion.go @@ -0,0 +1,83 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +package kernel + +import ( + "context" + "errors" + "fmt" + "net/http" + "slices" + + "github.com/kernel/kernel-go-sdk/internal/apijson" + "github.com/kernel/kernel-go-sdk/internal/requestconfig" + "github.com/kernel/kernel-go-sdk/option" + "github.com/kernel/kernel-go-sdk/packages/respjson" +) + +// Discover report types and submit typed reports against tasks. +// +// ReportTypeVersionService 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 [NewReportTypeVersionService] method instead. +type ReportTypeVersionService struct { + Options []option.RequestOption +} + +// NewReportTypeVersionService 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 NewReportTypeVersionService(opts ...option.RequestOption) (r ReportTypeVersionService) { + r = ReportTypeVersionService{} + r.Options = opts + return +} + +// Retrieve one schema version of a report type, including retired versions. +func (r *ReportTypeVersionService) Get(ctx context.Context, version int64, query ReportTypeVersionGetParams, opts ...option.RequestOption) (res *ReportTypeVersion, err error) { + opts = slices.Concat(r.Options, opts) + if query.Type == "" { + err = errors.New("missing required type parameter") + return nil, err + } + path := fmt.Sprintf("report_types/%s/versions/%v", query.Type, version) + err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...) + return res, err +} + +// One immutable schema version of a report type. +type ReportTypeVersion struct { + // Whether the version is retired. Retired versions are no longer accepted for new + // reports; existing reports keep them. + Retired bool `json:"retired" api:"required"` + // JSON Schema (draft 2020-12) that a report's data must match. Its field + // descriptions and examples describe what to send. + Schema map[string]any `json:"schema" api:"required"` + // Report type name, such as task.result + Type string `json:"type" api:"required"` + // Schema version number, starting at 1. + Version int64 `json:"version" api:"required"` + // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. + JSON struct { + Retired respjson.Field + Schema respjson.Field + Type respjson.Field + Version respjson.Field + ExtraFields map[string]respjson.Field + raw string + } `json:"-"` +} + +// Returns the unmodified JSON received from the API +func (r ReportTypeVersion) RawJSON() string { return r.JSON.raw } +func (r *ReportTypeVersion) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +type ReportTypeVersionGetParams struct { + Type string `path:"type" api:"required" json:"-"` + paramObj +} diff --git a/reporttypeversion_test.go b/reporttypeversion_test.go new file mode 100644 index 0000000..411efb6 --- /dev/null +++ b/reporttypeversion_test.go @@ -0,0 +1,43 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +package kernel_test + +import ( + "context" + "errors" + "os" + "testing" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/internal/testutil" + "github.com/kernel/kernel-go-sdk/option" +) + +func TestReportTypeVersionGet(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := kernel.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.ReportTypes.Versions.Get( + context.TODO(), + 0, + kernel.ReportTypeVersionGetParams{ + Type: "type", + }, + ) + if err != nil { + var apierr *kernel.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} diff --git a/task.go b/task.go new file mode 100644 index 0000000..12857f2 --- /dev/null +++ b/task.go @@ -0,0 +1,201 @@ +// 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" +) + +// Define tasks that agents work toward and link the browsers they use. +// +// TaskService 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 [NewTaskService] method instead. +type TaskService struct { + Options []option.RequestOption +} + +// NewTaskService 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 NewTaskService(opts ...option.RequestOption) (r TaskService) { + r = TaskService{} + r.Options = opts + return +} + +// Define a task before or while an agent works on it, optionally linking the +// browsers it uses. Submit reports against the returned task ID. +func (r *TaskService) New(ctx context.Context, body TaskNewParams, opts ...option.RequestOption) (res *Task, err error) { + opts = slices.Concat(r.Options, opts) + path := "tasks" + err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...) + return res, err +} + +// Retrieve a task and the IDs of its linked browsers. +func (r *TaskService) Get(ctx context.Context, id string, opts ...option.RequestOption) (res *Task, err error) { + opts = slices.Concat(r.Options, opts) + if id == "" { + err = errors.New("missing required id parameter") + return nil, err + } + path := fmt.Sprintf("tasks/%s", id) + err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...) + return res, err +} + +// List tasks in the request's project, newest first. +func (r *TaskService) List(ctx context.Context, query TaskListParams, opts ...option.RequestOption) (res *pagination.OffsetPagination[Task], err error) { + var raw *http.Response + opts = slices.Concat(r.Options, opts) + opts = append([]option.RequestOption{option.WithResponseInto(&raw)}, opts...) + path := "tasks" + 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 tasks in the request's project, newest first. +func (r *TaskService) ListAutoPaging(ctx context.Context, query TaskListParams, opts ...option.RequestOption) *pagination.OffsetPaginationAutoPager[Task] { + return pagination.NewOffsetPaginationAutoPager(r.List(ctx, query, opts...)) +} + +// Link browsers to an existing task. Linking a browser that is already linked has +// no effect, so the call is safe to retry. Returns the updated task. +func (r *TaskService) LinkBrowsers(ctx context.Context, id string, body TaskLinkBrowsersParams, opts ...option.RequestOption) (res *Task, err error) { + opts = slices.Concat(r.Options, opts) + if id == "" { + err = errors.New("missing required id parameter") + return nil, err + } + path := fmt.Sprintf("tasks/%s/browsers", id) + err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...) + return res, err +} + +// A goal an agent works toward. Reports are submitted against a task, and browsers +// can be linked to it. Tasks are immutable apart from added browser links. +type Task struct { + // Unique identifier for the task + ID string `json:"id" api:"required"` + // When the task was created + CreatedAt time.Time `json:"created_at" api:"required" format:"date-time"` + // What the task is meant to accomplish + Description string `json:"description" api:"required"` + // Caller-defined string key-value pairs for grouping and filtering tasks, such as + // a user or thread ID. At most 20 keys; keys are 1-64 characters, values at most + // 256 characters, and keys and values together at most 4 KB. + Metadata TaskMetadata `json:"metadata" api:"required"` + // IDs of browsers linked to the task, oldest link first. Linked browsers may since + // have been deleted. + SessionIDs []string `json:"session_ids" api:"required"` + // When work on the task started + StartedAt time.Time `json:"started_at" api:"required" format:"date-time"` + // Hostname of the website the task targets + TargetWebsite string `json:"target_website" api:"nullable"` + // JSON contains metadata for fields, check presence with [respjson.Field.Valid]. + JSON struct { + ID respjson.Field + CreatedAt respjson.Field + Description respjson.Field + Metadata respjson.Field + SessionIDs respjson.Field + StartedAt respjson.Field + TargetWebsite respjson.Field + ExtraFields map[string]respjson.Field + raw string + } `json:"-"` +} + +// Returns the unmodified JSON received from the API +func (r Task) RawJSON() string { return r.JSON.raw } +func (r *Task) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +type TaskMetadata map[string]string + +type TaskNewParams struct { + // What the task is meant to accomplish, at most 4 KB. + Description string `json:"description" api:"required"` + // When work on the task started. Defaults to the time the task is created. Must be + // no more than 5 minutes in the future or 30 days in the past. + StartedAt param.Opt[time.Time] `json:"started_at,omitzero" format:"date-time"` + // Hostname of the website the task targets, without a scheme or path. + TargetWebsite param.Opt[string] `json:"target_website,omitzero"` + // Caller-defined string key-value pairs for grouping and filtering tasks, such as + // a user or thread ID. At most 20 keys; keys are 1-64 characters, values at most + // 256 characters, and keys and values together at most 4 KB. + Metadata TaskMetadata `json:"metadata,omitzero"` + // IDs of browsers to link to the task. Each must belong to the request's project; + // deleted browsers can be linked. + SessionIDs []string `json:"session_ids,omitzero"` + paramObj +} + +func (r TaskNewParams) MarshalJSON() (data []byte, err error) { + type shadow TaskNewParams + return param.MarshalObject(r, (*shadow)(&r)) +} +func (r *TaskNewParams) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} + +type TaskListParams struct { + // Limit the number of tasks to return. + Limit param.Opt[int64] `query:"limit,omitzero" json:"-"` + // Offset the number of tasks to return. + Offset param.Opt[int64] `query:"offset,omitzero" json:"-"` + // Only return tasks linked to this browser ID. + SessionID param.Opt[string] `query:"session_id,omitzero" json:"-"` + paramObj +} + +// URLQuery serializes [TaskListParams]'s query parameters as `url.Values`. +func (r TaskListParams) URLQuery() (v url.Values, err error) { + return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{ + ArrayFormat: apiquery.ArrayQueryFormatComma, + NestedFormat: apiquery.NestedQueryFormatBrackets, + }) +} + +type TaskLinkBrowsersParams struct { + // IDs of browsers to link. Each must belong to the task's project; deleted + // browsers can be linked. Browsers already linked are ignored. A task can have at + // most 100 linked browsers. + SessionIDs []string `json:"session_ids,omitzero" api:"required"` + paramObj +} + +func (r TaskLinkBrowsersParams) MarshalJSON() (data []byte, err error) { + type shadow TaskLinkBrowsersParams + return param.MarshalObject(r, (*shadow)(&r)) +} +func (r *TaskLinkBrowsersParams) UnmarshalJSON(data []byte) error { + return apijson.UnmarshalRoot(data, r) +} diff --git a/task_test.go b/task_test.go new file mode 100644 index 0000000..e6f1dee --- /dev/null +++ b/task_test.go @@ -0,0 +1,126 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +package kernel_test + +import ( + "context" + "errors" + "os" + "testing" + "time" + + "github.com/kernel/kernel-go-sdk" + "github.com/kernel/kernel-go-sdk/internal/testutil" + "github.com/kernel/kernel-go-sdk/option" +) + +func TestTaskNewWithOptionalParams(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := kernel.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.Tasks.New(context.TODO(), kernel.TaskNewParams{ + Description: "Book a hotel room for two nights", + Metadata: kernel.TaskMetadata{ + "user_id": "user_123", + "thread_id": "thread_456", + }, + SessionIDs: []string{"x"}, + StartedAt: kernel.Time(time.Now()), + TargetWebsite: kernel.String("booking.com"), + }) + if err != nil { + var apierr *kernel.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} + +func TestTaskGet(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := kernel.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.Tasks.Get(context.TODO(), "id") + if err != nil { + var apierr *kernel.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} + +func TestTaskListWithOptionalParams(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := kernel.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.Tasks.List(context.TODO(), kernel.TaskListParams{ + Limit: kernel.Int(1), + Offset: kernel.Int(0), + SessionID: kernel.String("session_id"), + }) + if err != nil { + var apierr *kernel.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} + +func TestTaskLinkBrowsers(t *testing.T) { + t.Skip("Mock server tests are disabled") + baseURL := "http://localhost:4010" + if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok { + baseURL = envURL + } + if !testutil.CheckTestServer(t, baseURL) { + return + } + client := kernel.NewClient( + option.WithBaseURL(baseURL), + option.WithAPIKey("My API Key"), + ) + _, err := client.Tasks.LinkBrowsers( + context.TODO(), + "id", + kernel.TaskLinkBrowsersParams{ + SessionIDs: []string{"x"}, + }, + ) + if err != nil { + var apierr *kernel.Error + if errors.As(err, &apierr) { + t.Log(string(apierr.DumpRequest(true))) + } + t.Fatalf("err should be nil: %s", err.Error()) + } +} diff --git a/vaultitem.go b/vaultitem.go index 5cc7992..28c946f 100644 --- a/vaultitem.go +++ b/vaultitem.go @@ -312,14 +312,31 @@ type AgentcardCheckoutAuthorization struct { ActualCents int64 `json:"actual_cents"` // Display amount shown on the approval screen. Amount string `json:"amount"` - // Any of "display_only", "stripe_payment_intent". + // Source of the approved amount. `processor` is read from the processor request or + // payment; `agent` is the item's declared amount; `page` is the checkout page + // total; `none` means no amount was named. `display_only` appears only on + // authorizations recovered without a provider read. `agent` and `display_only` + // don't prove what the processor charged. + // + // Any of "processor", "agent", "page", "none", "display_only". AmountAuthority AgentcardCheckoutAuthorizationAmountAuthority `json:"amount_authority"` - AmountVerified bool `json:"amount_verified"` - ApprovalURL string `json:"approval_url" format:"uri"` + // Whether the processor charged the approved amount. Absent when there was no + // charge to compare, including tokenization checkouts. + AmountVerified bool `json:"amount_verified"` + ApprovalURL string `json:"approval_url" format:"uri"` // Browser session that submitted the checkout. - BrowserID string `json:"browser_id"` - ChargedAmountCents int64 `json:"charged_amount_cents"` - ChargedCurrency string `json:"charged_currency"` + BrowserID string `json:"browser_id"` + // Amount the processor reported collecting. Absent when the provider didn't + // observe a charge. + ChargedAmountCents int64 `json:"charged_amount_cents"` + // Currency of `charged_amount_cents`. Absent when the provider didn't observe a + // charge. + ChargedCurrency string `json:"charged_currency"` + // What the processor collected. `none` means the checkout produced a token or + // payment method that the merchant charges later. Absent when the provider + // reported nothing, which is common for tokenization checkouts; use item events + // and the merchant's order record instead. + // // Any of "captured", "authorized", "none". ChargedKind AgentcardCheckoutAuthorizationChargedKind `json:"charged_kind"` ExpectedCents int64 `json:"expected_cents"` @@ -376,13 +393,25 @@ const ( AgentcardCheckoutAuthorizationStatusExpired AgentcardCheckoutAuthorizationStatus = "expired" ) +// Source of the approved amount. `processor` is read from the processor request or +// payment; `agent` is the item's declared amount; `page` is the checkout page +// total; `none` means no amount was named. `display_only` appears only on +// authorizations recovered without a provider read. `agent` and `display_only` +// don't prove what the processor charged. type AgentcardCheckoutAuthorizationAmountAuthority string const ( - AgentcardCheckoutAuthorizationAmountAuthorityDisplayOnly AgentcardCheckoutAuthorizationAmountAuthority = "display_only" - AgentcardCheckoutAuthorizationAmountAuthorityStripePaymentIntent AgentcardCheckoutAuthorizationAmountAuthority = "stripe_payment_intent" + AgentcardCheckoutAuthorizationAmountAuthorityProcessor AgentcardCheckoutAuthorizationAmountAuthority = "processor" + AgentcardCheckoutAuthorizationAmountAuthorityAgent AgentcardCheckoutAuthorizationAmountAuthority = "agent" + AgentcardCheckoutAuthorizationAmountAuthorityPage AgentcardCheckoutAuthorizationAmountAuthority = "page" + AgentcardCheckoutAuthorizationAmountAuthorityNone AgentcardCheckoutAuthorizationAmountAuthority = "none" + AgentcardCheckoutAuthorizationAmountAuthorityDisplayOnly AgentcardCheckoutAuthorizationAmountAuthority = "display_only" ) +// What the processor collected. `none` means the checkout produced a token or +// payment method that the merchant charges later. Absent when the provider +// reported nothing, which is common for tokenization checkouts; use item events +// and the merchant's order record instead. type AgentcardCheckoutAuthorizationChargedKind string const ( @@ -10284,6 +10313,11 @@ type VaultItemEventsParams struct { IDOrName string `path:"id_or_name" api:"required" json:"-"` // Return events after this event ID. After param.Opt[string] `query:"after,omitzero" json:"-"` + // When true, also finds deleted items, and deleted vaults by ID only. `key` then + // also accepts an item ID, which takes precedence over a key with the same value; + // the lookup order is the item ID, then the live item with that key, then the most + // recently deleted one. `wait` is ignored for a deleted item or vault. + IncludeDeleted param.Opt[bool] `query:"include_deleted,omitzero" json:"-"` // Long-poll for new events for up to this many seconds. Wait param.Opt[int64] `query:"wait,omitzero" json:"-"` paramObj diff --git a/vaultitem_test.go b/vaultitem_test.go index fcbc0fa..80d6e5f 100644 --- a/vaultitem_test.go +++ b/vaultitem_test.go @@ -183,9 +183,10 @@ func TestVaultItemEventsWithOptionalParams(t *testing.T) { context.TODO(), "key", kernel.VaultItemEventsParams{ - IDOrName: "id_or_name", - After: kernel.String("after"), - Wait: kernel.Int(0), + IDOrName: "id_or_name", + After: kernel.String("after"), + IncludeDeleted: kernel.Bool(true), + Wait: kernel.Int(0), }, ) if err != nil {