From 5e54793d3628d6bae3242a208712ee83bca8ff70 Mon Sep 17 00:00:00 2001 From: brandonphelps1212 Date: Thu, 19 Nov 2026 19:13:52 -0500 Subject: [PATCH] add the convex plugin Signed-off-by: brandonphelps1212 Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- adapter/convex.go | 96 ++++++ adapter/convex_test.go | 91 +++++ docs/plugins.json | 12 +- docs/plugins.md | 1 + plugins/openapi/convex.go | 28 ++ plugins/openapi/convex_test.go | 154 +++++++++ plugins/openapi/openapi.go | 3 + plugins/openapi/registered_test.go | 2 +- plugins/openapi/testdata/README.md | 4 + plugins/openapi/testdata/convex-3ead9091.json | 309 +++++++++++++++++ plugins/openapi/testdata/convex-3f6edf7a.json | 321 ++++++++++++++++++ plugins/openapi/testdata/convex-5e5159cb.json | 301 ++++++++++++++++ plugins/openapi/testdata/convex-f35879bb.json | 295 ++++++++++++++++ plugins/openapi/testdata/golden/convex.json | 128 +++++++ providers/README.md | 1 + providers/convex.md | 48 +++ 17 files changed, 1793 insertions(+), 3 deletions(-) create mode 100644 adapter/convex.go create mode 100644 adapter/convex_test.go create mode 100644 plugins/openapi/convex.go create mode 100644 plugins/openapi/convex_test.go create mode 100644 plugins/openapi/testdata/convex-3ead9091.json create mode 100644 plugins/openapi/testdata/convex-3f6edf7a.json create mode 100644 plugins/openapi/testdata/convex-5e5159cb.json create mode 100644 plugins/openapi/testdata/convex-f35879bb.json create mode 100644 plugins/openapi/testdata/golden/convex.json create mode 100644 providers/convex.md diff --git a/README.md b/README.md index 2bd82bf..b25e164 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ [![Go Reference](https://pkg.go.dev/badge/github.com/patch-it-dev/patch-it-plugins.svg)](https://pkg.go.dev/github.com/patch-it-dev/patch-it-plugins) [![Go version](https://img.shields.io/github/go-mod/go-version/patch-it-dev/patch-it-plugins)](go.mod) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-3f5bf0)](LICENSE) -[![Plugins](https://img.shields.io/badge/plugins-24-3f5bf0)](docs/plugins.md) +[![Plugins](https://img.shields.io/badge/plugins-25-3f5bf0)](docs/plugins.md) [![Docs](https://img.shields.io/badge/docs-docs.patch--it.dev-3f5bf0)](https://docs.patch-it.dev) [![Discussions](https://img.shields.io/github/discussions/patch-it-dev/patch-it-plugins)](https://github.com/patch-it-dev/patch-it-plugins/discussions) diff --git a/adapter/convex.go b/adapter/convex.go new file mode 100644 index 0000000..d700ecb --- /dev/null +++ b/adapter/convex.go @@ -0,0 +1,96 @@ +package adapter + +import ( + "context" + "encoding/json" + "fmt" + "time" + + "github.com/patch-it-dev/patch-it-plugins/fetch" +) + +// Variables, not constants, only so tests can point them at a local server. +var ( + // convexCommitsURL lists the commits that changed the Deployment API + // spec in get-convex/convex-backend, newest first; with per_page=1, the + // newest. + convexCommitsURL = "https://api.github.com/repos/get-convex/convex-backend/commits?path=npm-packages/@convex-dev/platform/deployment-openapi.json&per_page=1" + // convexCommitURL is one commit, for its date. + convexCommitURL = "https://api.github.com/repos/get-convex/convex-backend/commits/%s" + // convexSpecURLTemplate is the Deployment API spec at one commit: 68 + // commits from 2025-08-19 to 2026-11-16 (checked 2026-11-19), and a + // commit never changes. + convexSpecURLTemplate = "https://raw.githubusercontent.com/get-convex/convex-backend/%s/npm-packages/@convex-dev/platform/deployment-openapi.json" +) + +// Convex adapts the Convex Deployment API spec (`{deployment-url}/api/v1`) +// in get-convex/convex-backend for the openapi plugin. A tag here is the +// commit that last changed the spec, as for Supabase. +// +// The repo does tag releases, `precompiled-YYYY-MM-DD-` (1,213 of +// them), but they are daily builds of the self-hosted backend, not releases +// of the API: several a day, ordered only by commit date, the spec unchanged +// in most. The spec at a tag is the spec at the last commit before it that +// changed the file, so reading those commits sees every state a tag would, +// with one GitHub call for the newest instead of paging through the tags. +type Convex struct{} + +var _ Adapter = Convex{} + +func (Convex) API() string { return "convex" } + +// LatestTag is the SHA of the newest commit that changed the spec. +func (Convex) LatestTag(ctx context.Context) (string, error) { + body, err := fetch.Get(ctx, convexCommitsURL, githubHeaders()) + if err != nil { + return "", fmt.Errorf("looking up convex's latest spec commit: %w", err) + } + var commits []struct { + SHA string `json:"sha"` + } + if err := json.Unmarshal(body, &commits); err != nil { + return "", fmt.Errorf("parsing github commits response: %w", err) + } + if len(commits) == 0 || commits[0].SHA == "" { + return "", fmt.Errorf("github lists no commit that changed the convex spec") + } + return commits[0].SHA, nil +} + +// Fetch downloads the spec at commit sha. +// +// Version is the commit's committer date (YYYY-MM-DD, UTC): the Deployment +// API has no version of its own (`/api/v1`, info.version a fixed "1.0.0" in +// every commit, checked 2026-11-19), so the date the spec changed is the +// closest thing to "the API version the change arrived in". +func (Convex) Fetch(ctx context.Context, sha string) (Spec, error) { + meta, err := fetch.Get(ctx, fmt.Sprintf(convexCommitURL, sha), githubHeaders()) + if err != nil { + return Spec{}, fmt.Errorf("looking up convex spec commit %s: %w", sha, err) + } + var commit struct { + SHA string `json:"sha"` + Commit struct { + Committer struct { + Date time.Time `json:"date"` + } `json:"committer"` + } `json:"commit"` + } + if err := json.Unmarshal(meta, &commit); err != nil { + return Spec{}, fmt.Errorf("parsing github commit %s: %w", sha, err) + } + if commit.SHA == "" || commit.Commit.Committer.Date.IsZero() { + return Spec{}, fmt.Errorf("github commit %s has no sha or date", sha) + } + // Pin to the full SHA even when given a short one: the citation must + // name exactly one document. + url := fmt.Sprintf(convexSpecURLTemplate, commit.SHA) + body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth + if err != nil { + return Spec{}, fmt.Errorf("fetching convex spec %s: %w", sha, err) + } + if !json.Valid(body) { + return Spec{}, fmt.Errorf("convex spec %s is not valid json", sha) + } + return Spec{Content: body, Version: commit.Commit.Committer.Date.UTC().Format("2006-01-02"), SourceURL: url}, nil +} diff --git a/adapter/convex_test.go b/adapter/convex_test.go new file mode 100644 index 0000000..503c7b0 --- /dev/null +++ b/adapter/convex_test.go @@ -0,0 +1,91 @@ +package adapter + +import ( + "context" + "net/http" + "net/http/httptest" + "strings" + "testing" +) + +// fakeConvexGitHub serves the commits list, one commit, and specs by path. +func fakeConvexGitHub(t *testing.T, commitsJSON string, commits, specs map[string]string) *httptest.Server { + t.Helper() + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch { + case r.URL.Path == "/commits": + w.Write([]byte(commitsJSON)) + case strings.HasPrefix(r.URL.Path, "/commits/"): + body, ok := commits[strings.TrimPrefix(r.URL.Path, "/commits/")] + if !ok { + http.Error(w, `{"message":"No commit found"}`, http.StatusUnprocessableEntity) + return + } + w.Write([]byte(body)) + default: + body, ok := specs[r.URL.Path] + if !ok { + http.NotFound(w, r) + return + } + w.Write([]byte(body)) + } + })) + t.Cleanup(srv.Close) + oldList, oldOne, oldSpec := convexCommitsURL, convexCommitURL, convexSpecURLTemplate + convexCommitsURL = srv.URL + "/commits" + convexCommitURL = srv.URL + "/commits/%s" + convexSpecURLTemplate = srv.URL + "/%s/spec.json" + t.Cleanup(func() { convexCommitsURL, convexCommitURL, convexSpecURLTemplate = oldList, oldOne, oldSpec }) + return srv +} + +const convexSHA = "5e5159cbea5188e9da5400febda1b031a233eea0" + +func TestConvexLatestTagIsTheNewestSpecCommit(t *testing.T) { + fakeConvexGitHub(t, `[{"sha":"`+convexSHA+`"},{"sha":"older"}]`, nil, nil) + tag, err := Convex{}.LatestTag(context.Background()) + if err != nil || tag != convexSHA { + t.Errorf("got %q, %v; want %s", tag, err, convexSHA) + } +} + +func TestConvexLatestTagRejectsNoCommit(t *testing.T) { + fakeConvexGitHub(t, `[]`, nil, nil) + if _, err := (Convex{}).LatestTag(context.Background()); err == nil { + t.Error("no commit: want an error") + } +} + +// The version is the commit's committer date, in UTC, since the Deployment +// API has none (its info.version is a fixed 1.0.0); the source is pinned to +// the full SHA even when a short one is asked for, and the content is passed +// through. +func TestConvexFetchPinsTheFullSHAAndDatesByCommit(t *testing.T) { + const body = `{"openapi":"3.1.0","info":{"version":"1.0.0"},"paths":{}}` + srv := fakeConvexGitHub(t, "", map[string]string{ + "5e5159cbea": `{"sha":"` + convexSHA + `","commit":{"committer":{"date":"2026-11-05T19:36:44-08:00"}}}`, + }, map[string]string{"/" + convexSHA + "/spec.json": body}) + spec, err := Convex{}.Fetch(context.Background(), "5e5159cbea") + if err != nil { + t.Fatal(err) + } + if spec.Version != "2026-11-06" || spec.SourceURL != srv.URL+"/"+convexSHA+"/spec.json" || string(spec.Content) != body { + t.Errorf("got version %q, url %s, content %s", spec.Version, spec.SourceURL, spec.Content) + } +} + +func TestConvexFetchFailures(t *testing.T) { + commit := `{"sha":"` + convexSHA + `","commit":{"committer":{"date":"2026-11-05T19:36:44Z"}}}` + for name, c := range map[string]struct{ commits, specs map[string]string }{ + "unknown commit": {nil, nil}, + "commit without date": {map[string]string{"x": `{"sha":"` + convexSHA + `"}`}, nil}, + "spec missing": {map[string]string{"x": commit}, nil}, + "invalid json": {map[string]string{"x": commit}, map[string]string{"/" + convexSHA + "/spec.json": ""}}, + } { + fakeConvexGitHub(t, "", c.commits, c.specs) + if _, err := (Convex{}).Fetch(context.Background(), "x"); err == nil { + t.Errorf("%s: want an error", name) + } + } +} diff --git a/docs/plugins.json b/docs/plugins.json index a54ff56..e8b8fdc 100644 --- a/docs/plugins.json +++ b/docs/plugins.json @@ -1,7 +1,7 @@ { "_comment": "Generated from the plugin registry and docs/plugins.md by `make plugins-json` (go run ./cmd/list-plugins). Don't edit by hand.", "$schema": "./plugins.schema.json", - "count": 24, + "count": 25, "plugins": [ { "id": "algolia-ingestion", @@ -63,6 +63,16 @@ "status": "live", "provider_page": "providers/cloudflare.md" }, + { + "id": "convex", + "provider": "Convex", + "layer": "api", + "watches": "Deployment API operations deprecated, and deprecated operations removed, between commits of the spec", + "format": "openapi", + "source_url": "https://github.com/get-convex/convex-backend", + "status": "live", + "provider_page": "providers/convex.md" + }, { "id": "datadog", "provider": "Datadog", diff --git a/docs/plugins.md b/docs/plugins.md index 5797161..c160236 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -20,6 +20,7 @@ The table between the `plugins:start` and `plugins:end` markers is also publishe | [`algolia-recommend`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/algolia.md) | Algolia | API | Recommend API operations deprecated, and deprecated operations removed, between releases of the spec | `openapi` | [algolia/api-clients-automation](https://github.com/algolia/api-clients-automation) (`specs/bundled/recommend.yml`) | live | | [`elasticsearch`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/elasticsearch.md) | Elastic | API | Elasticsearch REST API operations deprecated, and deprecated operations removed, between released minor versions of the spec | `openapi` | [elastic/elasticsearch-specification](https://github.com/elastic/elasticsearch-specification) (`output/openapi/elasticsearch-openapi.json`) | live | | [`sentry`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/sentry.md) | Sentry | API | REST API operations deprecated between releases of the spec, most of them in the operation's description | `openapi` | [getsentry/sentry releases](https://github.com/getsentry/sentry/releases) (`openapi-derefed.json` on each `api@` release) | live | +| [`convex`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/convex.md) | Convex | API | Deployment API operations deprecated, and deprecated operations removed, between commits of the spec | `openapi` | [get-convex/convex-backend](https://github.com/get-convex/convex-backend) (`npm-packages/@convex-dev/platform/deployment-openapi.json`) | live | | [`mongodb-atlas`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/mongodb-atlas.md) | MongoDB | API | Atlas Administration API versions deprecated and removed at their sunset date, per endpoint, from MongoDB's own API changelog | `apichangelog` | [mongodb/openapi `changelog/changelog.json`](https://github.com/mongodb/openapi/blob/main/changelog/changelog.json) | live | | [`openai-models`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/openai-models.md) | OpenAI | AI models | Model deprecations and shutdown dates (Chat Completions and Responses text models) | `retirements` | [OpenAI deprecations](https://developers.openai.com/api/docs/deprecations) | live | | [`anthropic-models`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/anthropic-models.md) | Anthropic | AI models | Model deprecations and retirement dates (Messages API models) | `retirements` | [Anthropic model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations) | live | diff --git a/plugins/openapi/convex.go b/plugins/openapi/convex.go new file mode 100644 index 0000000..ef58cc1 --- /dev/null +++ b/plugins/openapi/convex.go @@ -0,0 +1,28 @@ +package openapi + +import "github.com/patch-it-dev/patch-it-plugins/diff" + +// convexDiff is how the Convex Deployment API spec says what it says: +// +// - Deprecations use the `deprecated` flag, and the description says what +// to use instead ("Deprecated: use `GET /integrations` instead."), so the +// event quotes the whole operation, not the bare `true`. Convex's docs +// build drops flagged operations, "since they stay served only for +// existing callers" (npm-packages/docs/scripts/prepare-openapi-specs.js). +// - PathTemplates, as for every spec here: a renamed path parameter isn't a +// change for callers. None has been renamed in this spec yet. +var convexDiff = diff.Options{PathTemplates: true, QuoteDeprecatedOperation: true} + +// convexKeep keeps operation deprecations, and removals of operations the old +// spec had marked deprecated. In the spec's history (68 commits, 2025-08-19 +// to 2026-11-16) that's 6 events, all on 2026-11-05: the six log stream +// operations, deprecated for the /integrations ones added on 2026-10-30. +// No operation has left the spec. Everything else is dropped: +// +// - Request and response property changes: 18 property removals, 16 type +// changes and 10 schema removals over the history, most of them in the +// data sync, usage-limit and S3 export APIs. On 2026-07-14 the optional +// `name` left the usage-limit request and response, while the server +// didn't refuse a request that still sent it: see the drop test. +// - New operations: nobody has to fix code for a new endpoint. +var convexKeep = deprecationsOnly(convexDiff) diff --git a/plugins/openapi/convex_test.go b/plugins/openapi/convex_test.go new file mode 100644 index 0000000..81dc546 --- /dev/null +++ b/plugins/openapi/convex_test.go @@ -0,0 +1,154 @@ +package openapi + +import ( + "context" + "fmt" + "os" + "strings" + "testing" + + "github.com/patch-it-dev/patch-it-plugins/adapter" + "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/kit/kittest" +) + +// convexCommits are the spec commits saved under testdata/ (trimmed to the +// operations involved, values unchanged; checked 2026-11-19): short SHA -> +// full SHA and committer date. +var convexCommits = map[string][2]string{ + "f35879bb": {"f35879bb396491942bf8ecbc8ef5e4280499f89f", "2026-10-30"}, + "5e5159cb": {"5e5159cbea5188e9da5400febda1b031a233eea0", "2026-11-05"}, + "3f6edf7a": {"3f6edf7ab8f3f98e027f317633246a19348eabcc", "2026-07-14"}, + "3ead9091": {"3ead909103b7f5897f529c031e80991ad174b07e", "2026-07-14"}, +} + +// fakeConvexAdapter serves the saved copies, cited by the real URL each was +// copied from, as adapter.Convex.Fetch cites it. +type fakeConvexAdapter struct{ latest string } + +func (fakeConvexAdapter) API() string { return "convex" } + +func (f fakeConvexAdapter) LatestTag(context.Context) (string, error) { return f.latest, nil } + +func (fakeConvexAdapter) Fetch(_ context.Context, tag string) (adapter.Spec, error) { + c, ok := convexCommits[tag] + if !ok { + return adapter.Spec{}, fmt.Errorf("no saved copy for %s", tag) + } + body, err := os.ReadFile(convexFile(tag)) + if err != nil { + return adapter.Spec{}, err + } + return adapter.Spec{Content: body, Version: c[1], SourceURL: convexURL(tag)}, nil +} + +func convexFile(tag string) string { return "testdata/convex-" + tag + ".json" } + +func convexURL(tag string) string { + return "https://raw.githubusercontent.com/get-convex/convex-backend/" + convexCommits[tag][0] + "/npm-packages/@convex-dev/platform/deployment-openapi.json" +} + +// convexPlugin is the plugin exactly as registered, over the saved copies. +func convexPlugin(latest string) Plugin { + return Plugin{Adapter: fakeConvexAdapter{latest: latest}, Diff: convexDiff, Keep: convexKeep} +} + +// convexReplacements are the six log stream operations Convex deprecated on +// 2026-11-05, and the /integrations operation each description names +// instead (added 2026-10-30). The commit that deprecated them says "The +// routes still work, so existing callers and older dashboards keep working." +var convexReplacements = map[string]string{ + "GET /list_log_streams": "`GET /integrations`", + "GET /get_log_stream/{id}": "`GET /integrations/{id}`", + "POST /create_log_stream": "`POST /integrations`", + "POST /update_log_stream/{id}": "`PATCH /integrations/{id}`", + "POST /delete_log_stream/{id}": "`DELETE /integrations/{id}`", + "POST /rotate_webhook_secret/{id}": "`POST /integrations/{id}/rotate_webhook_secret`", +} + +// The golden test: the only deprecations in the Deployment API spec's +// history, replayed from the commit before (f35879bb) to the one that made +// them (5e5159cb). Each is a deprecation, not breaking, cites 5e5159cb, and +// quotes the whole operation, so the flag and the replacement are in the +// excerpt. +func TestConvexGolden(t *testing.T) { + ctx := context.Background() + s := openStore(t) + if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, convexPlugin(""), "f35879bb", "5e5159cb"); err != nil || rejected { + t.Fatalf("replay: rejected=%v err=%v", rejected, err) + } + events := kittest.Stored(t, s) + if len(events) != len(convexReplacements) { + for _, e := range events { + t.Logf("got: %s", e.Description) + } + t.Fatalf("stored %d events, want %d", len(events), len(convexReplacements)) + } + for _, e := range events { + instead, ok := convexReplacements[e.Subject.Operation] + if !ok { + t.Errorf("unexpected event %s", e.Subject.Operation) + continue + } + if e.ChangeType != event.ChangeTypeDeprecation || e.Breaking || e.Version != "2026-11-05" { + t.Errorf("%s: %s breaking=%v version %s, want a 2026-11-05 deprecation", e.Subject.Operation, e.ChangeType, e.Breaking, e.Version) + } + if e.SourceURL != convexURL("5e5159cb") { + t.Errorf("%s: source_url %s", e.Subject.Operation, e.SourceURL) + } + if node := jsonNode(t, convexFile("5e5159cb"), e.SourcePointer); node != e.SourceExcerpt && !truncated(e.SourceExcerpt, node) { + t.Errorf("%s: excerpt doesn't match 5e5159cb#%s", e.Subject.Operation, e.SourcePointer) + } + if !strings.Contains(e.SourceExcerpt, `"deprecated":true`) || !strings.Contains(e.SourceExcerpt, "Deprecated: use "+instead+" instead.") { + t.Errorf("%s: excerpt lacks the flag or %s: %.300s", e.Subject.Operation, instead, e.SourceExcerpt) + } + } + kittest.Golden(t, "testdata/golden/convex.json", events) + + // As a daily ingest, the same six events. + s = openStore(t) + env := vercelEnv(s) + for _, tag := range []string{"f35879bb", "5e5159cb"} { + if rejected, err := kittest.Run(ctx, env, s, convexPlugin(tag)); err != nil || rejected { + t.Fatalf("run %s: rejected=%v err=%v", tag, rejected, err) + } + } + if got := kittest.Stored(t, s); len(got) != len(convexReplacements) { + t.Errorf("ingest stored %d events, want %d", len(got), len(convexReplacements)) + } +} + +// The pinned drop test. On 2026-07-14 (3ead9091, "Remove name from usage +// limits") the optional, nullable `name` left the usage-limit request and +// response, unmarked. Convex's commit says it "was never editable in the UI +// (always `None` on create, only echoed back)", and the request type at that +// commit doesn't deny unknown fields, so a caller still sending it isn't +// rejected. No event. +func TestConvexDropsPropertyChangesThatWerentDeprecations(t *testing.T) { + ctx := context.Background() + s := openStore(t) + if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, convexPlugin(""), "3f6edf7a", "3ead9091"); err != nil || rejected { + t.Fatalf("replay: rejected=%v err=%v", rejected, err) + } + if events := kittest.Stored(t, s); len(events) != 0 { + t.Fatalf("stored %d events, want none", len(events)) + } + // Without the filter the same pair reports two breaking removals of + // `name`, one per schema, and nothing else. + s = openStore(t) + p := convexPlugin("") + p.Keep = nil + if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, "3f6edf7a", "3ead9091"); err != nil { + t.Fatal(err) + } + unfiltered := kittest.Stored(t, s) + var removed int + for _, e := range unfiltered { + if e.Breaking && strings.HasPrefix(e.Description, "Property name removed from schema UsageLimitConfig") { + removed++ + } + } + if removed != 2 || len(unfiltered) != 2 { + t.Errorf("unfiltered: %d events, %d of them `name` removals; want 2 and 2", len(unfiltered), removed) + } +} diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index 2ff5f48..e4d3a3c 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -49,6 +49,9 @@ func init() { // Operation deprecations only, most said in the description: see // sentry.go. plugin.Register(Plugin{Adapter: adapter.Sentry{}, Diff: sentryDiff, Keep: sentryKeep}) + // No Hints: Convex has no API changelog; its news feed is product news. + // Only operation deprecations and removals: see convex.go. + plugin.Register(Plugin{Adapter: adapter.Convex{}, Diff: convexDiff, Keep: convexKeep}) } // requestSide keeps the changes to what callers send. GitLab's response diff --git a/plugins/openapi/registered_test.go b/plugins/openapi/registered_test.go index 107e8fc..3f1b9f7 100644 --- a/plugins/openapi/registered_test.go +++ b/plugins/openapi/registered_test.go @@ -8,7 +8,7 @@ import ( ) func TestRegistersItself(t *testing.T) { - for _, a := range []adapter.Adapter{adapter.Stripe{}, adapter.Datadog{}, adapter.GitLab{}, adapter.GitHub{}, adapter.Vercel{}, adapter.Supabase{}, adapter.Algolia{Spec: "search"}, adapter.Algolia{Spec: "ingestion"}, adapter.Algolia{Spec: "recommend"}, adapter.Elasticsearch{}, adapter.Sentry{}} { + for _, a := range []adapter.Adapter{adapter.Stripe{}, adapter.Datadog{}, adapter.GitLab{}, adapter.GitHub{}, adapter.Vercel{}, adapter.Supabase{}, adapter.Algolia{Spec: "search"}, adapter.Algolia{Spec: "ingestion"}, adapter.Algolia{Spec: "recommend"}, adapter.Elasticsearch{}, adapter.Sentry{}, adapter.Convex{}} { kittest.Registered(t, Plugin{Adapter: a}) } } diff --git a/plugins/openapi/testdata/README.md b/plugins/openapi/testdata/README.md index 64df17c..bfb27c3 100644 --- a/plugins/openapi/testdata/README.md +++ b/plugins/openapi/testdata/README.md @@ -28,6 +28,8 @@ Each pair is a real breaking change between two releases of a provider's own spe | `sentry-2.0.1.json`, `sentry-2.1.0.json` | https://raw.githubusercontent.com/getsentry/sentry-api-schema/2.0.1/openapi-derefed.json (and `2.1.0`) | 2026-11-19 | FSL-1.1-Apache-2.0 (getsentry/sentry-api-schema; the spec's own `info.license` says Apache 2.0) | `"url": "https://{region}.sentry.io"` and `"/api/0/organizations/": {` (in `2.0.1`), `"url": "https://{region}.sentry.io/api/0"` and `"/organizations/": {` (in `2.1.0`): the drop test | | `sentry-94bc6e59.json`, `sentry-d15557ff.json` | https://raw.githubusercontent.com/getsentry/sentry-api-schema/94bc6e593eaf8a3800341abd429d2949895926fd/openapi-derefed.json (and `d15557ff7472748887043ab8a72687b20214a9bd`) | 2026-11-19 | Apache 2.0 (the spec's own `info.license`; getsentry/sentry-api-schema had no license file before 2026-02-10) | "**Eventsv2 Deprecation Note**: Users who may be using the `eventsv2` endpoint should update their requests to the `events` endpoint" (`GET .../events/`, new in `d15557ff`; not a deprecation of it) | | `sentry-e8ec23b4.json`, `sentry-1ef7f21a.json` | https://raw.githubusercontent.com/getsentry/sentry-api-schema/e8ec23b4c9601dea2d51205983ec1d7b89550b85/openapi-derefed.json (and `1ef7f21a0501fae9490d69e3ae29f0d5acbfb61c`) | 2026-11-19 | FSL-1.1-Apache-2.0 (getsentry/sentry-api-schema; the spec's own `info.license` says Apache 2.0) | "a brief description, examples, and deprecation details." (`GET .../trace-items/attributes/`, new in `1ef7f21a`; not a deprecation) | +| `convex-f35879bb.json`, `convex-5e5159cb.json` | https://raw.githubusercontent.com/get-convex/convex-backend/f35879bb396491942bf8ecbc8ef5e4280499f89f/npm-packages/@convex-dev/platform/deployment-openapi.json (and `5e5159cbea5188e9da5400febda1b031a233eea0`) | 2026-11-19 | FSL-1.1-Apache-2.0 (get-convex/convex-backend `LICENSE.md`; the spec's own `info.license` is `LicenseRef-FSL-1.1-Apache-2.0`): excerpt for testing, © Convex, Inc.; maintainers, please confirm | "Deprecated: use `GET /integrations` instead." (`GET /list_log_streams`, and five more log stream operations, new in `5e5159cb`) | +| `convex-3f6edf7a.json`, `convex-3ead9091.json` | https://raw.githubusercontent.com/get-convex/convex-backend/3f6edf7ab8f3f98e027f317633246a19348eabcc/npm-packages/@convex-dev/platform/deployment-openapi.json (and `3ead909103b7f5897f529c031e80991ad174b07e`) | 2026-11-19 | FSL-1.1-Apache-2.0 (get-convex/convex-backend `LICENSE.md`; the spec's own `info.license` is `LicenseRef-FSL-1.1-Apache-2.0`): excerpt for testing, © Convex, Inc.; maintainers, please confirm | `"name": {` in `UsageLimitConfigRequest` and `UsageLimitConfigResponse` (in `3f6edf7a`, gone in `3ead9091` without being deprecated): the drop test | The Elasticsearch copies keep `openapi`, `info` and the paths involved, every line unchanged; the 9.2 copy's paths are all gone in 9.2, so its `"paths": {}` is the one line that isn't in the original. @@ -37,4 +39,6 @@ The Supabase copies keep each value unchanged but are re-indented: the source is The Sentry copies keep `openapi`, `info`, `servers` and the path items involved, whole, in their original order except that `servers` comes before `paths`, every line copied unchanged (bar the trailing comma after a path item that's now last); `components` and `tags` left out. Each pair gives the same events as the full files, with the filter and with the variants the tests use (flag only, "deprecat" anywhere). The tests serve them as GitHub would, with each commit's date and each tag's release date. +The Convex copies keep `openapi`, `info`, `servers` and the path items involved, whole and in their original order, every line copied unchanged (bar the trailing comma after a path item or schema that's now last); the usage-limit pair also keeps the component schemas those operations reach, the log stream pair none. The source is FSL-1.1-Apache-2.0 (each version becomes Apache-2.0 two years after it's published), which allows copying for a permitted purpose; these are short excerpts kept for testing, but a maintainer should confirm that before release. Each pair gives the same changes as the full files, with and without the filter. The management API spec (`management-openapi.json`, `info.license` `LicenseRef-Convex`, not defined anywhere in the repo) is neither read nor saved. + Stripe's spec isn't saved here: its tests use small specs written inline. diff --git a/plugins/openapi/testdata/convex-3ead9091.json b/plugins/openapi/testdata/convex-3ead9091.json new file mode 100644 index 0000000..f0de886 --- /dev/null +++ b/plugins/openapi/testdata/convex-3ead9091.json @@ -0,0 +1,309 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Convex Deployment API", + "description": "Admin API for interacting with deployments.", + "license": { + "name": "LicenseRef-FSL-1.1-Apache-2.0", + "identifier": "LicenseRef-FSL-1.1-Apache-2.0" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "{deployment-url}/api/v1", + "description": "Your Convex deployment", + "variables": { + "deployment-url": { + "default": "https://happy-animal-123.convex.cloud", + "description": "Your deployment URL" + } + } + } + ], + "paths": { + "/list_usage_limits": { + "get": { + "tags": [ + "Usage Limits" + ], + "summary": "List usage limits", + "description": "Get all usage limit configs for a deployment.", + "operationId": "list_usage_limits", + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListUsageLimitsResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/create_usage_limit": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Create usage limit", + "description": "Create a new usage limit config for a deployment.", + "operationId": "create_usage_limit", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitConfigRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/update_usage_limit/{id}": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Update usage limit", + "description": "Replace an existing usage limit config for a deployment.", + "operationId": "update_usage_limit", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the usage limit to update", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitConfigRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/delete_usage_limit/{id}": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Delete usage limit", + "description": "Delete an existing usage limit config for a deployment.", + "operationId": "delete_usage_limit", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the usage limit to delete", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "" + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + } + }, + "components": { + "schemas": { + "ListUsageLimitsResponse": { + "type": "object", + "required": [ + "usageLimits" + ], + "properties": { + "usageLimits": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UsageLimitConfigResponse" + } + } + } + }, + "UsageLimitConfigRequest": { + "type": "object", + "required": [ + "metric", + "window", + "limitType", + "limit", + "enabled" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "limit": { + "type": "integer", + "format": "int64", + "minimum": 1 + }, + "limitType": { + "type": "string" + }, + "metric": { + "$ref": "#/components/schemas/UsageLimitMetric" + }, + "window": { + "type": "string" + } + } + }, + "UsageLimitConfigResponse": { + "type": "object", + "required": [ + "id", + "metric", + "window", + "limitType", + "limit", + "enabled" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "id": { + "type": "string" + }, + "limit": { + "type": "integer", + "format": "int64", + "minimum": 1 + }, + "limitType": { + "type": "string" + }, + "metric": { + "$ref": "#/components/schemas/UsageLimitMetric" + }, + "window": { + "type": "string" + } + } + }, + "UsageLimitMetric": { + "type": "string", + "enum": [ + "functionCalls", + "databaseIoGb", + "dataEgressGb", + "searchQueryGb", + "queryMutationComputeGbHours", + "actionComputeConvexGbHours", + "actionComputeNodeJsGbHours", + "actionComputeCpuGbHours" + ] + }, + "UsageLimitResponse": { + "type": "object", + "required": [ + "usageLimit" + ], + "properties": { + "usageLimit": { + "$ref": "#/components/schemas/UsageLimitConfigResponse" + } + } + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/convex-3f6edf7a.json b/plugins/openapi/testdata/convex-3f6edf7a.json new file mode 100644 index 0000000..929c4a2 --- /dev/null +++ b/plugins/openapi/testdata/convex-3f6edf7a.json @@ -0,0 +1,321 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Convex Deployment API", + "description": "Admin API for interacting with deployments.", + "license": { + "name": "LicenseRef-FSL-1.1-Apache-2.0", + "identifier": "LicenseRef-FSL-1.1-Apache-2.0" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "{deployment-url}/api/v1", + "description": "Your Convex deployment", + "variables": { + "deployment-url": { + "default": "https://happy-animal-123.convex.cloud", + "description": "Your deployment URL" + } + } + } + ], + "paths": { + "/list_usage_limits": { + "get": { + "tags": [ + "Usage Limits" + ], + "summary": "List usage limits", + "description": "Get all usage limit configs for a deployment.", + "operationId": "list_usage_limits", + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListUsageLimitsResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/create_usage_limit": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Create usage limit", + "description": "Create a new usage limit config for a deployment.", + "operationId": "create_usage_limit", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitConfigRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/update_usage_limit/{id}": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Update usage limit", + "description": "Replace an existing usage limit config for a deployment.", + "operationId": "update_usage_limit", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the usage limit to update", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitConfigRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UsageLimitResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/delete_usage_limit/{id}": { + "post": { + "tags": [ + "Usage Limits" + ], + "summary": "Delete usage limit", + "description": "Delete an existing usage limit config for a deployment.", + "operationId": "delete_usage_limit", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the usage limit to delete", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "" + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + } + }, + "components": { + "schemas": { + "ListUsageLimitsResponse": { + "type": "object", + "required": [ + "usageLimits" + ], + "properties": { + "usageLimits": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UsageLimitConfigResponse" + } + } + } + }, + "UsageLimitConfigRequest": { + "type": "object", + "required": [ + "metric", + "window", + "limitType", + "limit", + "enabled" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "limit": { + "type": "integer", + "format": "int64", + "minimum": 1 + }, + "limitType": { + "type": "string" + }, + "metric": { + "$ref": "#/components/schemas/UsageLimitMetric" + }, + "name": { + "type": [ + "string", + "null" + ] + }, + "window": { + "type": "string" + } + } + }, + "UsageLimitConfigResponse": { + "type": "object", + "required": [ + "id", + "metric", + "window", + "limitType", + "limit", + "enabled" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "id": { + "type": "string" + }, + "limit": { + "type": "integer", + "format": "int64", + "minimum": 1 + }, + "limitType": { + "type": "string" + }, + "metric": { + "$ref": "#/components/schemas/UsageLimitMetric" + }, + "name": { + "type": [ + "string", + "null" + ] + }, + "window": { + "type": "string" + } + } + }, + "UsageLimitMetric": { + "type": "string", + "enum": [ + "functionCalls", + "databaseIoGb", + "dataEgressGb", + "searchQueryGb", + "queryMutationComputeGbHours", + "actionComputeConvexGbHours", + "actionComputeNodeJsGbHours", + "actionComputeCpuGbHours" + ] + }, + "UsageLimitResponse": { + "type": "object", + "required": [ + "usageLimit" + ], + "properties": { + "usageLimit": { + "$ref": "#/components/schemas/UsageLimitConfigResponse" + } + } + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/convex-5e5159cb.json b/plugins/openapi/testdata/convex-5e5159cb.json new file mode 100644 index 0000000..13f1d8c --- /dev/null +++ b/plugins/openapi/testdata/convex-5e5159cb.json @@ -0,0 +1,301 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Convex Deployment API", + "description": "Admin API for interacting with deployments.", + "license": { + "name": "LicenseRef-FSL-1.1-Apache-2.0", + "identifier": "LicenseRef-FSL-1.1-Apache-2.0" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "{deployment-url}/api/v1", + "description": "Your Convex deployment", + "variables": { + "deployment-url": { + "default": "https://happy-animal-123.convex.cloud", + "description": "Your deployment URL" + } + } + } + ], + "paths": { + "/list_log_streams": { + "get": { + "tags": [ + "Log Streams" + ], + "summary": "List log streams", + "description": "List configs for all existing log streams in a deployment.\n\nDeprecated: use `GET /integrations` instead.", + "operationId": "list_log_streams", + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LogStreamConfig" + } + } + } + } + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/get_log_stream/{id}": { + "get": { + "tags": [ + "Log Streams" + ], + "summary": "Get log stream", + "description": "Get the config for a specific log stream by id.\n\nDeprecated: use `GET /integrations/{id}` instead.", + "operationId": "get_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to retrieve", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LogStreamConfig" + } + } + } + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/delete_log_stream/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Delete log stream", + "description": "Delete the deployment's log stream with the given id.\n\nDeprecated: use `DELETE /integrations/{id}` instead.", + "operationId": "delete_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to delete", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "" + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/create_log_stream": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Create log stream", + "description": "Create a new log stream for the deployment. Errors if a log stream of the\ngiven type already exists.\n\nDeprecated: use `POST /integrations` instead.", + "operationId": "create_log_stream", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateLogStreamArgs" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateLogStreamResponse" + } + } + } + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/update_log_stream/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Update log stream", + "description": "Update an existing log stream for the deployment. Omit a field to keep the\nexisting value, and use `null` to unset a field.\n\nDeprecated: use `PATCH /integrations/{id}` instead.", + "operationId": "update_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to update", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateLogStreamArgs" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "" + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/rotate_webhook_secret/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Rotate webhook log stream secret", + "description": "Rotate the secret for the webhook log stream.\n\nDeprecated: use `POST /integrations/{id}/rotate_webhook_secret` instead.", + "operationId": "rotate_webhook_secret", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the webhook log stream for which to rotate the secret", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RotateLogStreamSecretResponse" + } + } + } + } + }, + "deprecated": true, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/convex-f35879bb.json b/plugins/openapi/testdata/convex-f35879bb.json new file mode 100644 index 0000000..79a4fa2 --- /dev/null +++ b/plugins/openapi/testdata/convex-f35879bb.json @@ -0,0 +1,295 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Convex Deployment API", + "description": "Admin API for interacting with deployments.", + "license": { + "name": "LicenseRef-FSL-1.1-Apache-2.0", + "identifier": "LicenseRef-FSL-1.1-Apache-2.0" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "{deployment-url}/api/v1", + "description": "Your Convex deployment", + "variables": { + "deployment-url": { + "default": "https://happy-animal-123.convex.cloud", + "description": "Your deployment URL" + } + } + } + ], + "paths": { + "/list_log_streams": { + "get": { + "tags": [ + "Log Streams" + ], + "summary": "List log streams", + "description": "List configs for all existing log streams in a deployment.", + "operationId": "list_log_streams", + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LogStreamConfig" + } + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/get_log_stream/{id}": { + "get": { + "tags": [ + "Log Streams" + ], + "summary": "Get log stream", + "description": "Get the config for a specific log stream by id.", + "operationId": "get_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to retrieve", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LogStreamConfig" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/delete_log_stream/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Delete log stream", + "description": "Delete the deployment's log stream with the given id.", + "operationId": "delete_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to delete", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "" + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/create_log_stream": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Create log stream", + "description": "Create a new log stream for the deployment. Errors if a log stream of the\ngiven type already exists.", + "operationId": "create_log_stream", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateLogStreamArgs" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateLogStreamResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/update_log_stream/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Update log stream", + "description": "Update an existing log stream for the deployment. Omit a field to keep the\nexisting value, and use `null` to unset a field.", + "operationId": "update_log_stream", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the log stream to update", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateLogStreamArgs" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "" + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + }, + "/rotate_webhook_secret/{id}": { + "post": { + "tags": [ + "Log Streams" + ], + "summary": "Rotate webhook log stream secret", + "description": "Rotate the secret for the webhook log stream.", + "operationId": "rotate_webhook_secret", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "id of the webhook log stream for which to rotate the secret", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RotateLogStreamSecretResponse" + } + } + } + } + }, + "security": [ + { + "Deploy Key": [] + }, + { + "OAuth Team Token": [] + }, + { + "Team Token": [] + }, + { + "OAuth Project Token": [] + } + ] + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/golden/convex.json b/plugins/openapi/testdata/golden/convex.json new file mode 100644 index 0000000..e5ccfa7 --- /dev/null +++ b/plugins/openapi/testdata/golden/convex.json @@ -0,0 +1,128 @@ +[ + { + "id": 1, + "fingerprint": "sha256:62859868bbcc378eda3869e6f5ab6a4c9e64ad38e2280118d199454b119fc970", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /create_log_stream" + }, + "description": "Operation POST /create_log_stream marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1create_log_stream/post", + "source_excerpt": "{\"deprecated\":true,\"description\":\"Create a new log stream for the deployment. Errors if a log stream of the\\ngiven type already exists.\\n\\nDeprecated: use `POST /integrations` instead.\",\"operationId\":\"create_log_stream\",\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/CreateLogStreamArgs\"}}},\"required\":true},\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/CreateLogStreamResponse\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Create log stream\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 2, + "fingerprint": "sha256:2300b4593102ca6b7793c3de6aeee09e0297553a3165f2064bb27c6c51774b9c", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /delete_log_stream/{id}" + }, + "description": "Operation POST /delete_log_stream/{id} marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1delete_log_stream~1{id}/post", + "source_excerpt": "{\"deprecated\":true,\"description\":\"Delete the deployment's log stream with the given id.\\n\\nDeprecated: use `DELETE /integrations/{id}` instead.\",\"operationId\":\"delete_log_stream\",\"parameters\":[{\"description\":\"id of the log stream to delete\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Delete log stream\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 3, + "fingerprint": "sha256:0199cb8ceb6df6cbfd3b64ac63232e658807648d0793bef31c3a7449a39710d3", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "GET /get_log_stream/{id}" + }, + "description": "Operation GET /get_log_stream/{id} marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1get_log_stream~1{id}/get", + "source_excerpt": "{\"deprecated\":true,\"description\":\"Get the config for a specific log stream by id.\\n\\nDeprecated: use `GET /integrations/{id}` instead.\",\"operationId\":\"get_log_stream\",\"parameters\":[{\"description\":\"id of the log stream to retrieve\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/LogStreamConfig\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Get log stream\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 4, + "fingerprint": "sha256:05c99279b9caebabc67c362c1fd50549802502a5af820fb54edfd96b3f2bf09d", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "GET /list_log_streams" + }, + "description": "Operation GET /list_log_streams marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1list_log_streams/get", + "source_excerpt": "{\"deprecated\":true,\"description\":\"List configs for all existing log streams in a deployment.\\n\\nDeprecated: use `GET /integrations` instead.\",\"operationId\":\"list_log_streams\",\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"items\":{\"$ref\":\"#/components/schemas/LogStreamConfig\"},\"type\":\"array\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"List log streams\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 5, + "fingerprint": "sha256:a497cc27410c958d2fe98f2ea1406c9a099e6dfcd090ae949986ad757917cae4", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /rotate_webhook_secret/{id}" + }, + "description": "Operation POST /rotate_webhook_secret/{id} marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1rotate_webhook_secret~1{id}/post", + "source_excerpt": "{\"deprecated\":true,\"description\":\"Rotate the secret for the webhook log stream.\\n\\nDeprecated: use `POST /integrations/{id}/rotate_webhook_secret` instead.\",\"operationId\":\"rotate_webhook_secret\",\"parameters\":[{\"description\":\"id of the webhook log stream for which to rotate the secret\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/RotateLogStreamSecretResponse\"}}},\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Rotate webhook log stream secret\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + }, + { + "id": 6, + "fingerprint": "sha256:5b6797cfbe4242ebee3473c97b0af28f93e913923237aa1ed0273ba76ed26d2c", + "api": "convex", + "version": "2026-11-05", + "previous_version": "2026-10-30", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /update_log_stream/{id}" + }, + "description": "Operation POST /update_log_stream/{id} marked deprecated.", + "source_url": "https://raw.githubusercontent.com/get-convex/convex-backend/5e5159cbea5188e9da5400febda1b031a233eea0/npm-packages/@convex-dev/platform/deployment-openapi.json", + "source_pointer": "/paths/~1update_log_stream~1{id}/post", + "source_excerpt": "{\"deprecated\":true,\"description\":\"Update an existing log stream for the deployment. Omit a field to keep the\\nexisting value, and use `null` to unset a field.\\n\\nDeprecated: use `PATCH /integrations/{id}` instead.\",\"operationId\":\"update_log_stream\",\"parameters\":[{\"description\":\"id of the log stream to update\",\"in\":\"path\",\"name\":\"id\",\"required\":true,\"schema\":{\"type\":\"string\"}}],\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/UpdateLogStreamArgs\"}}},\"required\":true},\"responses\":{\"200\":{\"description\":\"\"}},\"security\":[{\"Deploy Key\":[]},{\"OAuth Team Token\":[]},{\"Team Token\":[]},{\"OAuth Project Token\":[]}],\"summary\":\"Update log stream\",\"tags\":[\"Log Streams\"]}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + } +] diff --git a/providers/README.md b/providers/README.md index 9e5821f..6349a08 100644 --- a/providers/README.md +++ b/providers/README.md @@ -19,6 +19,7 @@ One page per plugin id: `providers/.md`. Start from [`_template.md`](_templ | [algolia.md](algolia.md) | `algolia-search`, `algolia-ingestion`, `algolia-recommend` | `openapi` | | [elasticsearch.md](elasticsearch.md) | `elasticsearch` | `openapi` | | [sentry.md](sentry.md) | `sentry` | `openapi` | +| [convex.md](convex.md) | `convex` | `openapi` | | [openai-models.md](openai-models.md) | `openai-models` | `retirements` | | [anthropic-models.md](anthropic-models.md) | `anthropic-models` | `retirements` | | [anthropic.md](anthropic.md) | `anthropic` | `migrationguide` | diff --git a/providers/convex.md b/providers/convex.md new file mode 100644 index 0000000..bb97f32 --- /dev/null +++ b/providers/convex.md @@ -0,0 +1,48 @@ +# Convex (`convex`) + +## What it watches + +The Convex Deployment API (`{deployment-url}/api/v1`, the platform API for managing one deployment: environment variables, log streams and integrations, usage limits, data sync): operations Convex marks deprecated, and removals of operations it had marked deprecated, between two versions of the API's OpenAPI spec. + +Format plugin: `openapi` (`plugins/openapi`), with `adapter.Convex`. + +## Why this source + +- **Source:** `npm-packages/@convex-dev/platform/deployment-openapi.json` in [get-convex/convex-backend](https://github.com/get-convex/convex-backend), pinned to the commit that last changed it (`https://raw.githubusercontent.com/get-convex/convex-backend//npm-packages/@convex-dev/platform/deployment-openapi.json`). The newest such commit comes from the GitHub commits API. Checked on 2026-11-19. +- **Why a commit, not a release tag:** the repo tags `precompiled-YYYY-MM-DD-` builds (1,213 of them), but those are daily builds of the self-hosted backend, not releases of the API. There are several on some days, ordered only by commit date, and the spec is the same in most of them. The spec at a tag is the spec at the last commit before it that changed the file, so the commits see every version a tag would, and finding the newest takes one call instead of paging through the tags. A commit never changes, so it can be cited and replayed. +- **Why this one:** + - It's Convex's own description of the API: its docs build renders the API reference from it. + - It marks deprecations with the `deprecated` flag and says what to use instead ("Deprecated: use `GET /integrations` instead."). Convex's docs build drops flagged operations, "since they stay served only for existing callers" (`npm-packages/docs/scripts/prepare-openapi-specs.js`). + - There are 68 versions from 2025-08-19, when the spec was added, to 2026-11-16. +- **Alternatives considered:** + - **The Management API spec** (`management-openapi.json`, next to it: teams, projects, deployments). Its `info.license` is `LicenseRef-Convex`, which nothing in the repo defines, so the plugin neither reads nor saves it. + - **The SDK changelogs** (`convex` on npm, `get-convex/convex-js` `CHANGELOG.md`; `convex-py`). One flat list of bullets per version (95 versions in `convex-js`), with no removed or deprecated sections for the `changelog` plugin to read. + - **[Convex News](https://news.convex.dev/)** (RSS at `https://news.convex.dev/rss/`). Product news and announcements, newest post 2026-09-21; it doesn't name API operations. + - **The `@convex-dev/platform` npm package** (0.1.11). Its tarball has only `package.json` and the generated client, not the specs. +- **Quote:** "Deprecated: use `GET /integrations` instead." (`GET /list_log_streams`, deprecated in the spec on 2026-11-05) + +## How the provider announces changes + +- **No API version beyond `/api/v1`.** `info.version` is `1.0.0` in every commit, so the event's `version` is the spec commit's committer date (UTC), the closest thing to the API version a change arrived in. The patch-it client keeps a date-versioned API's events only if it's in its list of date-versioned APIs, so `convex` needs to be in it. +- **The spec changes a few times a month,** mostly with new operations and properties as Convex builds out the platform API. +- **Deprecations are rare:** one so far. On 2026-10-30 (`f35879bb`, "Rename log_streaming to integrations") Convex added six `/integrations` operations; on 2026-11-05 (`5e5159cb`) it marked the six log stream operations deprecated, each naming its replacement. The commit says "The routes still work, so existing callers and older dashboards keep working." + +## What the plugin reads and ignores + +- **Reads:** the spec at the newest commit, diffed against the last one. Two events come out of it: + - **Deprecations:** an operation that gains the `deprecated` flag. The event quotes the whole operation, so the replacement Convex names is in the excerpt. + - **Removals (breaking):** an operation that leaves the spec after the previous spec had marked it deprecated. None yet. +- **Operations are named as the spec writes them,** relative to the server URL `{deployment-url}/api/v1`: `GET /list_log_streams` is `GET {deployment-url}/api/v1/list_log_streams`. The server URL has been `/api/v1` since the first commit. +- **Matches operations by path template,** as for every spec here. No path parameter has been renamed in this spec yet. +- **Ignores everything else:** + - **Request and response property changes,** and new operations. Over the history the differ finds 18 property removals, 16 type changes and 10 schema removals, most of them in the data sync, usage-limit and S3 export APIs. The drop test is one of them: on 2026-07-14 (`3ead9091`, "Remove name from usage limits") the optional `name` left the usage-limit request and response; the commit says it "was never editable in the UI (always `None` on create, only echoed back)", and the request type at that commit doesn't reject unknown fields, so a caller still sending it isn't refused. + - **Removals of operations that were never deprecated.** None in the history: no operation has left the spec. +- Over the 68 commits this keeps 6 events, all deprecations on 2026-11-05: `GET /list_log_streams`, `GET /get_log_stream/{id}`, `POST /create_log_stream`, `POST /update_log_stream/{id}`, `POST /delete_log_stream/{id}`, `POST /rotate_webhook_secret/{id}`. +- **Replays** a historical pair (`Replay`, from `f35879bb` to `5e5159cb`) and recreates those six; the golden test also runs them as a daily ingest. The drop test replays `3f6edf7a` to `3ead9091`. + +## Known gaps + +- **Only the Deployment API is covered.** Not the Management API (see above), the client SDKs (`convex` on npm, `convex-py`), or the functions runtime. SDK removals are written as plain bullets in their changelogs, so nothing reads them yet. +- **Removals Convex doesn't mark first aren't events,** even if the endpoint really went away. None has happened yet. +- **Two spec commits on one day share a `version`.** It happened on 13 days in the history. The events stay distinct, because the operation is part of the fingerprint, but the second run's `previous_version` equals its `version`. +- **The patch-it client can't place these events until `convex` is in its list of date-versioned APIs.**