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/neon.go b/adapter/neon.go new file mode 100644 index 0000000..920b3a2 --- /dev/null +++ b/adapter/neon.go @@ -0,0 +1,106 @@ +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 ( + // neonCommitsURL lists the commits that changed the Neon API spec in + // neondatabase/neon-pkgs, newest first; with per_page=1, the newest. + neonCommitsURL = "https://api.github.com/repos/neondatabase/neon-pkgs/commits?path=packages/sdk/spec/neon-openapi.json&per_page=1" + // neonCommitURL is one commit, for its date. + neonCommitURL = "https://api.github.com/repos/neondatabase/neon-pkgs/commits/%s" + // neonSpecURLTemplate is the Neon API spec (console.neon.tech/api/v2) at + // one commit. Neon serves it live at + // https://neon.com/api_spec/release/v2.json, which has no versions; the + // copy in neondatabase/neon-pkgs is pulled from there and committed when + // a daily drift check sees it change (23 commits from 2026-06-24 to + // 2026-11-17), and a commit never changes. + neonSpecURLTemplate = "https://raw.githubusercontent.com/neondatabase/neon-pkgs/%s/packages/sdk/spec/neon-openapi.json" +) + +// Neon adapts the Neon API spec in neondatabase/neon-pkgs for the openapi +// plugin. The repo tags no spec releases, so a tag here is the commit that +// last changed the spec. +type Neon struct{} + +var _ Adapter = Neon{} + +func (Neon) API() string { return "neon" } + +// LatestTag is the SHA of the newest commit that changed the spec. +func (Neon) LatestTag(ctx context.Context) (string, error) { + body, err := fetch.Get(ctx, neonCommitsURL, githubHeaders()) + if err != nil { + return "", fmt.Errorf("looking up neon'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 neon spec") + } + return commits[0].SHA, nil +} + +// Fetch downloads the spec at commit sha and moves the server URL's path into +// the paths: see ServerBasePath. +// +// Version is the commit's date (YYYY-MM-DD): the API's only version is the +// `/api/v2` in its URL (info.version a fixed "v2" in all 23 commits, checked +// 2026-11-19), so the date the spec changed is the closest thing to "the API +// version the change arrived in". +func (Neon) Fetch(ctx context.Context, sha string) (Spec, error) { + meta, err := fetch.Get(ctx, fmt.Sprintf(neonCommitURL, sha), githubHeaders()) + if err != nil { + return Spec{}, fmt.Errorf("looking up neon 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(neonSpecURLTemplate, commit.SHA) + body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth + if err != nil { + return Spec{}, fmt.Errorf("fetching neon spec %s: %w", sha, err) + } + if !json.Valid(body) { + return Spec{}, fmt.Errorf("neon spec %s is not valid json", sha) + } + // The server is "https://console.neon.tech/api/v2" and the paths don't + // repeat /api/v2 (all 23 commits, checked 2026-11-19). Moved into the + // paths, an operation is named by the path a caller sends, and a spec + // that ever moved it (as Sentry's did) can't read as every deprecated + // operation removed. + content, err := ServerBasePath(body) + if err != nil { + return Spec{}, fmt.Errorf("neon spec %s: %w", sha, err) + } + return Spec{Content: content, Version: commit.Commit.Committer.Date.UTC().Format("2006-01-02"), SourceURL: url}, nil +} + +// SourcePointer: see BasePathPointer. +func (Neon) SourcePointer(content []byte) func(string) string { return BasePathPointer(content) } + +var _ Reshaper = Neon{} diff --git a/adapter/neon_test.go b/adapter/neon_test.go new file mode 100644 index 0000000..545b6d7 --- /dev/null +++ b/adapter/neon_test.go @@ -0,0 +1,118 @@ +package adapter + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" +) + +// fakeNeonGitHub serves the commits list, one commit, and specs by path. +func fakeNeonGitHub(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 := neonCommitsURL, neonCommitURL, neonSpecURLTemplate + neonCommitsURL = srv.URL + "/commits" + neonCommitURL = srv.URL + "/commits/%s" + neonSpecURLTemplate = srv.URL + "/%s/spec.json" + t.Cleanup(func() { neonCommitsURL, neonCommitURL, neonSpecURLTemplate = oldList, oldOne, oldSpec }) + return srv +} + +const neonSHA = "93b93dc9e4d1b4ab48dac6c8ccba76b35541b476" + +func TestNeonLatestTagIsTheNewestSpecCommit(t *testing.T) { + fakeNeonGitHub(t, `[{"sha":"`+neonSHA+`"},{"sha":"older"}]`, nil, nil) + tag, err := Neon{}.LatestTag(context.Background()) + if err != nil || tag != neonSHA { + t.Errorf("got %q, %v; want %s", tag, err, neonSHA) + } +} + +func TestNeonLatestTagRejectsNoCommit(t *testing.T) { + fakeNeonGitHub(t, `[]`, nil, nil) + if _, err := (Neon{}).LatestTag(context.Background()); err == nil { + t.Error("no commit: want an error") + } +} + +// The version is the commit's date, since the API has none (its +// info.version is a fixed v2); the source is pinned to the full SHA even +// when a short one is asked for, and a spec whose server has no path is +// passed through byte for byte. +func TestNeonFetchPinsTheFullSHAAndDatesByCommit(t *testing.T) { + const body = `{"openapi":"3.0.3","info":{"version":"v2"},"paths":{}}` + srv := fakeNeonGitHub(t, "", map[string]string{ + "93b93dc9": `{"sha":"` + neonSHA + `","commit":{"committer":{"date":"2026-08-23T11:50:46Z"}}}`, + }, map[string]string{"/" + neonSHA + "/spec.json": body}) + spec, err := Neon{}.Fetch(context.Background(), "93b93dc9") + if err != nil { + t.Fatal(err) + } + if spec.Version != "2026-08-23" || spec.SourceURL != srv.URL+"/"+neonSHA+"/spec.json" || string(spec.Content) != body { + t.Errorf("got version %q, url %s, content %s", spec.Version, spec.SourceURL, spec.Content) + } +} + +func TestNeonFetchFailures(t *testing.T) { + commit := `{"sha":"` + neonSHA + `","commit":{"committer":{"date":"2026-08-23T11:50:46Z"}}}` + for name, c := range map[string]struct{ commits, specs map[string]string }{ + "unknown commit": {nil, nil}, + "commit without date": {map[string]string{"x": `{"sha":"` + neonSHA + `"}`}, nil}, + "spec missing": {map[string]string{"x": commit}, nil}, + "invalid json": {map[string]string{"x": commit}, map[string]string{"/" + neonSHA + "/spec.json": ""}}, + } { + fakeNeonGitHub(t, "", c.commits, c.specs) + if _, err := (Neon{}).Fetch(context.Background(), "x"); err == nil { + t.Errorf("%s: want an error", name) + } + } +} + +// Neon's server is "https://console.neon.tech/api/v2": Fetch moves /api/v2 +// into the paths, so an operation is named by the path a caller sends, and +// SourcePointer points back into the path as published. +func TestNeonFetchMovesTheServerPathIntoThePaths(t *testing.T) { + const body = `{"openapi":"3.0.3","servers":[{"url":"https://console.neon.tech/api/v2"}],"paths":{"/projects":{"get":{}}}}` + fakeNeonGitHub(t, "", map[string]string{ + "93b93dc9": `{"sha":"` + neonSHA + `","commit":{"committer":{"date":"2026-08-23T11:50:46Z"}}}`, + }, map[string]string{"/" + neonSHA + "/spec.json": body}) + spec, err := Neon{}.Fetch(context.Background(), "93b93dc9") + if err != nil { + t.Fatal(err) + } + var doc struct { + Paths map[string]any `json:"paths"` + } + if err := json.Unmarshal(spec.Content, &doc); err != nil { + t.Fatal(err) + } + if _, ok := doc.Paths["/api/v2/projects"]; !ok || len(doc.Paths) != 1 { + t.Errorf("paths %v, want only /api/v2/projects", doc.Paths) + } + if got := (Neon{}).SourcePointer(spec.Content)("/paths/~1api~1v2~1projects/get"); got != "/paths/~1projects/get" { + t.Errorf("SourcePointer = %s, want /paths/~1projects/get", got) + } +} diff --git a/adapter/sentry.go b/adapter/sentry.go index 5b5fb4f..7b66eba 100644 --- a/adapter/sentry.go +++ b/adapter/sentry.go @@ -118,7 +118,7 @@ func (r sentryReleaseInfo) hasSpec() bool { // Fetch downloads the spec of an api@X.Y.Z release (the release's asset), or // of a sentry-api-schema tag or commit (the file at it), and moves the -// server URL's path into the paths: see sentryBasePath. +// server URL's path into the paths: see ServerBasePath. // // Version is the release's publication date, or a commit's date // (YYYY-MM-DD): the API has no version of its own (`/api/0`, info.version @@ -173,7 +173,7 @@ func (s Sentry) Fetch(ctx context.Context, tag string) (Spec, error) { if err != nil { return Spec{}, fmt.Errorf("fetching the sentry %s spec: %w", tag, err) } - content, err := sentryBasePath(body) + content, err := ServerBasePath(body) if err != nil { return Spec{}, fmt.Errorf("sentry %s: %w", tag, err) } @@ -195,13 +195,18 @@ func sentryReleaseMeta(ctx context.Context, url, tag string) (sentryReleaseInfo, return r, nil } -// sentryBasePathKey is the root key Fetch records the server path it moved +// basePathKey is the root key ServerBasePath records the server path it moved // into the paths under. The differ reads only paths and components, so the // key is never diffed. -const sentryBasePathKey = "x-patch-it-base-path" +const basePathKey = "x-patch-it-base-path" -// sentryBasePath puts the server URL's path back at the front of every path. +// ServerBasePath puts the server URL's path back at the front of every path, +// so an operation is named by the path a caller sends ("GET /api/0/…"), and +// a spec that moves the server's path into its paths (or out of them) reads +// as the same operations, not as every operation removed and added again. +// Used by every adapter whose API has a path in its server URL. // +// Sentry did move it: // Until sentry-api-schema 2.0.1 the server was "https://{region}.sentry.io" // and the paths started "/api/0/"; from 2.1.0 (2026-11-13) the server is // "https://{region}.sentry.io/api/0" and the paths don't. The URLs a caller @@ -213,7 +218,7 @@ const sentryBasePathKey = "x-patch-it-base-path" // A spec whose server has no path is returned byte for byte. The values are // otherwise unchanged (numbers kept as written); the path moved is recorded // for SourcePointer. -func sentryBasePath(body []byte) ([]byte, error) { +func ServerBasePath(body []byte) ([]byte, error) { dec := json.NewDecoder(bytes.NewReader(body)) dec.UseNumber() var doc map[string]any @@ -241,7 +246,7 @@ func sentryBasePath(body []byte) ([]byte, error) { moved[base+p] = item } doc["paths"] = moved - doc[sentryBasePathKey] = base + doc[basePathKey] = base return json.Marshal(doc) } @@ -260,10 +265,14 @@ func serverPath(u string) string { return strings.TrimRight(rest[i:], "/") } -// SourcePointer turns a pointer into a path Fetch prefixed with the server's -// path back into one into the path as published. Every other pointer, and -// every pointer into a spec Fetch didn't change, is already right. -func (Sentry) SourcePointer(content []byte) func(string) string { +// SourcePointer: see BasePathPointer. +func (Sentry) SourcePointer(content []byte) func(string) string { return BasePathPointer(content) } + +// BasePathPointer turns a pointer into a path ServerBasePath prefixed with +// the server's path back into one into the path as published. Every other +// pointer, and every pointer into a spec ServerBasePath didn't change, is +// already right. +func BasePathPointer(content []byte) func(string) string { var doc struct { Base string `json:"x-patch-it-base-path"` } diff --git a/adapter/sentry_test.go b/adapter/sentry_test.go index eb70ccf..81f29cb 100644 --- a/adapter/sentry_test.go +++ b/adapter/sentry_test.go @@ -162,10 +162,10 @@ func TestSentryFetchSchemaTagOrCommit(t *testing.T) { } func TestSentryBasePathRefusesWhatItCantMove(t *testing.T) { - if _, err := sentryBasePath([]byte(`{"servers":[{"url":"https://x/api"}],"paths":{"/a":{},"a":{}}}`)); err == nil { + if _, err := ServerBasePath([]byte(`{"servers":[{"url":"https://x/api"}],"paths":{"/a":{},"a":{}}}`)); err == nil { t.Error("a path without a leading /: want an error") } - if _, err := sentryBasePath([]byte(`{"servers":[{"url":"https://x/api/0"},{"url":"https://y"}],"paths":{}}`)); err == nil { + if _, err := ServerBasePath([]byte(`{"servers":[{"url":"https://x/api/0"},{"url":"https://y"}],"paths":{}}`)); err == nil { t.Error("servers with different paths: want an error") } } diff --git a/docs/plugins.json b/docs/plugins.json index a54ff56..86b7ea8 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", @@ -123,6 +123,16 @@ "status": "live", "provider_page": "providers/mongodb-atlas.md" }, + { + "id": "neon", + "provider": "Neon", + "layer": "api", + "watches": "Neon API operations deprecated, and deprecated operations removed, between commits of the spec", + "format": "openapi", + "source_url": "https://github.com/neondatabase/neon-pkgs", + "status": "live", + "provider_page": "providers/neon.md" + }, { "id": "newrelic", "provider": "New Relic", diff --git a/docs/plugins.md b/docs/plugins.md index 5797161..be79095 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 | +| [`neon`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/providers/neon.md) | Neon | API | Neon API operations deprecated, and deprecated operations removed, between commits of the spec | `openapi` | [neondatabase/neon-pkgs](https://github.com/neondatabase/neon-pkgs) (`packages/sdk/spec/neon-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/neon.go b/plugins/openapi/neon.go new file mode 100644 index 0000000..41a70ee --- /dev/null +++ b/plugins/openapi/neon.go @@ -0,0 +1,33 @@ +package openapi + +import "github.com/patch-it-dev/patch-it-plugins/diff" + +// neonDiff is how the Neon API spec says what it says: +// +// - Deprecations use the `deprecated` flag, and only the flag: in the 23 +// commits of neondatabase/neon-pkgs's copy (2026-06-24 to 2026-11-17) no +// operation is described as deprecated without it. (Two unflagged +// operations deprecate a parameter in words; those aren't operation +// deprecations.) +// A flagged operation's description says why or when ("Deprecated: to +// test a branch's already-saved configuration, use +// `sendNeonAuthEmailProviderTest`", "Removal scheduled for March 1, +// 2026"), and every one carries an `x-sunset` date, so the event quotes +// the whole operation, not the bare `true`. +// - Path parameters could be renamed without the URL changing; none was in +// this history, but matching by path template costs nothing here and +// keeps a rename from reading as a removal. +var neonDiff = diff.Options{PathTemplates: true, QuoteDeprecatedOperation: true} + +// neonKeep keeps operation deprecations, and removals of operations the old +// spec had marked deprecated. In the spec's history that's 1 event: POST +// /projects/{project_id}/branches/{branch_id}/auth/send_test_email, +// deprecated on 2026-08-23. Everything else is dropped: +// +// - One operation left the spec, not deprecated first: POST +// /projects/{project_id}/branches/{branch_id}/recover on 2026-08-09. +// neon-pkgs's own PR for it (#408) says it "was not removed from the API. +// It was removed from the published spec": it still routes. +// - Request and response property changes, new operations: not changes a +// caller has to fix, or not ones the spec's history shows reliably. +var neonKeep = deprecationsOnly(neonDiff) diff --git a/plugins/openapi/neon_test.go b/plugins/openapi/neon_test.go new file mode 100644 index 0000000..8a5c483 --- /dev/null +++ b/plugins/openapi/neon_test.go @@ -0,0 +1,198 @@ +package openapi + +import ( + "context" + "encoding/json" + "fmt" + "os" + "strings" + "testing" + + "gopkg.in/yaml.v3" + + "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" +) + +// neonCommits are the spec commits saved under testdata/ (trimmed to the +// operations involved, every kept line unchanged; checked 2026-11-19): short +// SHA -> full SHA and committer date. The spec's own license is +// "Proprietary", so only these excerpts are saved, never the whole file. +var neonCommits = map[string][2]string{ + "5c57d009": {"5c57d0095a9a4594a3c8b09d499b132902e7c42e", "2026-08-17"}, + "93b93dc9": {"93b93dc9e4d1b4ab48dac6c8ccba76b35541b476", "2026-08-23"}, + "4c6b3be4": {"4c6b3be46b1b333e7f910db51218ad144de27179", "2026-07-25"}, + "4497de89": {"4497de89a5e84b38956fde686d271f99317b8fdb", "2026-08-09"}, +} + +// fakeNeonAdapter serves the saved copies, cited by the real URL each was +// copied from and reshaped, as adapter.Neon.Fetch cites and reshapes it. +type fakeNeonAdapter struct{ latest string } + +func (fakeNeonAdapter) API() string { return "neon" } + +func (f fakeNeonAdapter) LatestTag(context.Context) (string, error) { return f.latest, nil } + +func (fakeNeonAdapter) Fetch(_ context.Context, tag string) (adapter.Spec, error) { + c, ok := neonCommits[tag] + if !ok { + return adapter.Spec{}, fmt.Errorf("no saved copy for %s", tag) + } + body, err := os.ReadFile(neonFile(tag)) + if err != nil { + return adapter.Spec{}, err + } + // As adapter.Neon.Fetch does: /api/v2 moved from the server URL into the + // paths. + content, err := adapter.ServerBasePath(body) + if err != nil { + return adapter.Spec{}, err + } + return adapter.Spec{Content: content, Version: c[1], SourceURL: neonURL(tag)}, nil +} + +func (fakeNeonAdapter) SourcePointer(content []byte) func(string) string { + return adapter.BasePathPointer(content) +} + +func neonFile(tag string) string { return "testdata/neon-" + tag + ".json" } + +func neonURL(tag string) string { + return "https://raw.githubusercontent.com/neondatabase/neon-pkgs/" + neonCommits[tag][0] + "/packages/sdk/spec/neon-openapi.json" +} + +// neonPlugin is the plugin exactly as registered, over the given adapter. +func neonPlugin(a adapter.Adapter) Plugin { + return Plugin{Adapter: a, Diff: neonDiff, Keep: neonKeep} +} + +// The golden test, the replay fixture: the one operation Neon deprecated in +// neon-pkgs's copy of the spec. On 2026-08-23 POST +// /projects/{project_id}/branches/{branch_id}/auth/send_test_email (beta) +// gained the flag, an x-sunset of 2027-02-28 and "Deprecated: to test a +// branch's already-saved configuration, use `sendNeonAuthEmailProviderTest`". +// The same commit added that operation (dropped: new), and GET +// .../auth/email_server, deprecated in both, is no new event. +func TestNeonGolden(t *testing.T) { + ctx := context.Background() + s := openStore(t) + if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, neonPlugin(fakeNeonAdapter{}), "5c57d009", "93b93dc9"); err != nil || rejected { + t.Fatalf("replay: rejected=%v err=%v", rejected, err) + } + events := kittest.Stored(t, s) + if len(events) != 1 { + for _, e := range events { + t.Logf("got: %s", e.Description) + } + t.Fatalf("stored %d events, want 1", len(events)) + } + e := events[0] + if e.Subject.Operation != "POST /api/v2/projects/{project_id}/branches/{branch_id}/auth/send_test_email" || e.Version != "2026-08-23" || e.PreviousVersion != "2026-08-17" { + t.Errorf("got %s %s (after %s)", e.Subject.Operation, e.Version, e.PreviousVersion) + } + if e.ChangeType != event.ChangeTypeDeprecation || e.Breaking { + t.Errorf("%s, want a deprecation", e.ChangeType) + } + if e.SourceURL != neonURL("93b93dc9") { + t.Errorf("source_url %s", e.SourceURL) + } + // The whole operation is quoted, so the reason and the sunset are in it. + if node := jsonNode(t, neonFile("93b93dc9"), e.SourcePointer); node != e.SourceExcerpt && !truncated(e.SourceExcerpt, node) { + t.Errorf("excerpt doesn't match 93b93dc9#%s", e.SourcePointer) + } + for _, want := range []string{`"deprecated":true`, "use `sendNeonAuthEmailProviderTest`", `"x-sunset":"2027-02-28"`} { + if !strings.Contains(e.SourceExcerpt, want) { + t.Errorf("excerpt lacks %s: %.300s", want, e.SourceExcerpt) + } + } + kittest.Golden(t, "testdata/golden/neon.json", events) +} + +// The pinned drop test. On 2026-08-09 POST +// /projects/{project_id}/branches/{branch_id}/recover left the spec without +// ever being marked deprecated. neon-pkgs's PR #408 checked: "The endpoint +// was not removed from the API. It was removed from the published spec." No +// event. +func TestNeonDropsRemovalsThatWerentDeprecated(t *testing.T) { + ctx := context.Background() + s := openStore(t) + if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, neonPlugin(fakeNeonAdapter{}), "4c6b3be4", "4497de89"); 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 the removal. + s = openStore(t) + p := neonPlugin(fakeNeonAdapter{}) + p.Keep = nil + if _, err := kittest.Replay(ctx, vercelEnv(s), s, p, "4c6b3be4", "4497de89"); err != nil { + t.Fatal(err) + } + var removals []string + for _, e := range kittest.Stored(t, s) { + if e.ChangeType == event.ChangeTypeBreaking && strings.HasPrefix(e.Description, "Operation ") && strings.HasSuffix(e.Description, " removed.") { + removals = append(removals, e.Subject.Operation) + } + } + if len(removals) != 1 || removals[0] != "POST /api/v2/projects/{project_id}/branches/{branch_id}/recover" { + t.Errorf("unfiltered removals %v, want only POST .../branches/{branch_id}/recover", removals) + } +} + +// neonAPIClient is a different source from the plugin's: the same spec as +// shipped (YAML) in the npm package @neondatabase/api-client, which @neon/sdk +// succeeded (no release since 2.7.3, 2026-07-01). neon-pkgs's history starts on +// 2026-06-24, after the one removal Neon announced, so the rule for removals +// is checked here, on real Neon data: GET /consumption_history/account, +// deprecated (with x-sunset 2026-06-01) in 2.7.2, gone in 2.7.3. Neon's +// changelog of 2026-04-03 called it "deprecated, with a planned sunset of June +// 1, 2026", and that of 2026-06-19 "The deprecated `GET +// /consumption_history/account` endpoint has been removed." +type neonAPIClient struct{} + +func (neonAPIClient) API() string { return "neon" } + +func (neonAPIClient) LatestTag(context.Context) (string, error) { return "2.7.3", nil } + +func (neonAPIClient) Fetch(_ context.Context, version string) (adapter.Spec, error) { + body, err := os.ReadFile("testdata/neon-api-client-" + version + ".yaml") + if err != nil { + return adapter.Spec{}, err + } + var doc any + if err := yaml.Unmarshal(body, &doc); err != nil { + return adapter.Spec{}, err + } + content, err := json.Marshal(doc) + if err != nil { + return adapter.Spec{}, err + } + if content, err = adapter.ServerBasePath(content); err != nil { // as adapter.Neon.Fetch does + return adapter.Spec{}, err + } + return adapter.Spec{Content: content, Version: version, SourceURL: "https://registry.npmjs.org/@neondatabase/api-client/-/api-client-" + version + ".tgz"}, nil +} + +func TestNeonKeepsTheRemovalOfADeprecatedOperation(t *testing.T) { + ctx := context.Background() + s := openStore(t) + if rejected, err := kittest.Replay(ctx, vercelEnv(s), s, neonPlugin(neonAPIClient{}), "2.7.2", "2.7.3"); err != nil || rejected { + t.Fatalf("replay: rejected=%v err=%v", rejected, err) + } + events := kittest.Stored(t, s) + if len(events) != 1 { + for _, e := range events { + t.Logf("got: %s", e.Description) + } + t.Fatalf("stored %d events, want 1", len(events)) + } + e := events[0] + if e.Subject.Operation != "GET /api/v2/consumption_history/account" || e.ChangeType != event.ChangeTypeBreaking || !e.Breaking { + t.Errorf("got %s %s breaking=%v, want GET /consumption_history/account removed", e.Subject.Operation, e.ChangeType, e.Breaking) + } + if !strings.Contains(e.SourceExcerpt, `"deprecated":true`) { + t.Errorf("excerpt lacks the flag the removal was kept for: %.300s", e.SourceExcerpt) + } +} diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index 2ff5f48..33f7c43 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -1,9 +1,9 @@ // Package openapi is the source plugin for an API that publishes an OpenAPI // spec per release (Stripe, Datadog, GitLab, GitHub, Vercel, Supabase, -// Algolia, Elasticsearch, Sentry): fetch the newest spec, diff it against the -// last one seen, normalize the changes into events, and attach migration -// hints from the API's changelog when it has one. It can also replay two -// given releases. +// Algolia, Elasticsearch, Sentry, Neon): fetch the newest spec, diff it +// against the last one seen, normalize the changes into events, and attach +// migration hints from the API's changelog when it has one. It can also replay +// two given releases. package openapi import ( @@ -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: Neon's changelog is a weekly digest, not keyed by operation. + // Only operation deprecations and removals: see neon.go. + plugin.Register(Plugin{Adapter: adapter.Neon{}, Diff: neonDiff, Keep: neonKeep}) } // 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..45afa1b 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.Neon{}} { kittest.Registered(t, Plugin{Adapter: a}) } } diff --git a/plugins/openapi/testdata/README.md b/plugins/openapi/testdata/README.md index 64df17c..71383af 100644 --- a/plugins/openapi/testdata/README.md +++ b/plugins/openapi/testdata/README.md @@ -28,6 +28,9 @@ 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) | +| `neon-5c57d009.json`, `neon-93b93dc9.json` | https://raw.githubusercontent.com/neondatabase/neon-pkgs/5c57d0095a9a4594a3c8b09d499b132902e7c42e/packages/sdk/spec/neon-openapi.json (and `93b93dc9e4d1b4ab48dac6c8ccba76b35541b476`) | 2026-11-19 | Excerpt for testing; © Neon. neondatabase/neon-pkgs is Apache-2.0, but the spec's own `info.license` says "Proprietary" | "Deprecated: to test a branch's already-saved configuration, use `sendNeonAuthEmailProviderTest`" (`POST /projects/{project_id}/branches/{branch_id}/auth/send_test_email`, new in `93b93dc9`) | +| `neon-4c6b3be4.json`, `neon-4497de89.json` | https://raw.githubusercontent.com/neondatabase/neon-pkgs/4c6b3be46b1b333e7f910db51218ad144de27179/packages/sdk/spec/neon-openapi.json (and `4497de89a5e84b38956fde686d271f99317b8fdb`) | 2026-11-19 | Excerpt for testing; © Neon. neondatabase/neon-pkgs is Apache-2.0, but the spec's own `info.license` says "Proprietary" | `"/projects/{project_id}/branches/{branch_id}/recover": {` (in `4c6b3be4`, gone in `4497de89` without being deprecated): the drop test | +| `neon-api-client-2.7.2.yaml`, `neon-api-client-2.7.3.yaml` | `public-v2-for-users.gen.yaml` in https://registry.npmjs.org/@neondatabase/api-client/-/api-client-2.7.2.tgz (and `api-client-2.7.3.tgz`) | 2026-11-19 | Excerpt for testing; © Neon. The package is MIT, but the spec's own `info.license` says "Proprietary" | "**Deprecated.** Use `GET /consumption_history/projects` (`getConsumptionHistoryPerProject`)" (`GET /consumption_history/account`, in 2.7.2, gone in 2.7.3) | 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 +40,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 Neon copies are excerpts, not whole files: the spec says its license is "Proprietary" whatever the license of the repo or package that ships it. The JSON copies keep `openapi`, `servers`, `info` (without its `contact`) and the path items involved, whole and in their original order, every line copied unchanged (bar the trailing comma after a member that's now last); `components` left out. The YAML copies keep, by lines, `openapi`, `servers`, `info`'s `title`, `version` and `license`, and the path items involved; they're a different source from the plugin's (the npm package @neondatabase/api-client, succeeded by @neon/sdk and not released since 2.7.3), used only to check that the removal of an operation marked deprecated is kept. + Stripe's spec isn't saved here: its tests use small specs written inline. diff --git a/plugins/openapi/testdata/golden/neon.json b/plugins/openapi/testdata/golden/neon.json new file mode 100644 index 0000000..e37eeec --- /dev/null +++ b/plugins/openapi/testdata/golden/neon.json @@ -0,0 +1,23 @@ +[ + { + "id": 1, + "fingerprint": "sha256:ddffac6cdf8e522e71a5059177f72c13d0f91fdcfcbaab724df5a0aa14666f9c", + "api": "neon", + "version": "2026-08-23", + "previous_version": "2026-08-17", + "change_type": "deprecation", + "breaking": false, + "subject": { + "type": "api_operation", + "kind": "operation", + "side": "request", + "operation": "POST /api/v2/projects/{project_id}/branches/{branch_id}/auth/send_test_email" + }, + "description": "Operation POST /api/v2/projects/{project_id}/branches/{branch_id}/auth/send_test_email marked deprecated.", + "source_url": "https://raw.githubusercontent.com/neondatabase/neon-pkgs/93b93dc9e4d1b4ab48dac6c8ccba76b35541b476/packages/sdk/spec/neon-openapi.json", + "source_pointer": "/paths/~1projects~1{project_id}~1branches~1{branch_id}~1auth~1send_test_email/post", + "source_excerpt": "{\"deprecated\":true,\"description\":\"Sends a test email using the SMTP server settings supplied in the request body to verify connectivity and credentials.\\nThe request body must include the full SMTP server settings\\n(`host`, `port`, `username`, `password`, `sender_email`, `sender_name`) and the `recipient_email` address.\\n\\nDeprecated: to test a branch's already-saved configuration, use `sendNeonAuthEmailProviderTest`, which\\nreuses the stored SMTP password server-side so the caller never has to re-supply (or be able to read) it.\\nThis endpoint remains available for testing an unsaved full configuration and for non-Better-Auth providers.\\n\",\"operationId\":\"sendNeonAuthTestEmail\",\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/SendNeonAuthTestEmailRequest\"}}},\"required\":true},\"responses\":{\"200\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/SendNeonAuthTestEmailResponse\"}}},\"description\":\"Response with the result of the test email send\"},\"default\":{\"$ref\":\"#/components/responses/GeneralError\"}},\"summary\":\"Send test email\",\"tags\":[\"Auth\"],\"x-stability-level\":\"beta\",\"x-sunset\":\"2027-02-28\"}", + "confidence": 1, + "detected_at": "2026-11-14T12:00:00Z" + } +] diff --git a/plugins/openapi/testdata/neon-4497de89.json b/plugins/openapi/testdata/neon-4497de89.json new file mode 100644 index 0000000..97236d4 --- /dev/null +++ b/plugins/openapi/testdata/neon-4497de89.json @@ -0,0 +1,56 @@ +{ + "openapi": "3.0.3", + "servers": [ + { + "url": "https://console.neon.tech/api/v2" + } + ], + "info": { + "title": "Neon API", + "description": "The Neon API is the management API for Neon. Use it to provision, configure, and manage resources such as projects, branches, databases, roles, functions, and object storage.\n\nSee the [Neon API reference](https://neon.com/docs/reference/api) for details, and [Manage API keys](https://neon.com/docs/manage/api-keys/) to create and use API keys.", + "version": "v2", + "license": { + "name": "Proprietary" + } + }, + "paths": { + "/projects/{project_id}/recover": { + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The Neon project ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + } + ], + "post": { + "summary": "Recover a deleted project", + "description": "Recovers a deleted project within the 7-day deletion recovery period.\nRestores branches, endpoints, settings, and connection strings.\nSome integrations require manual reconfiguration after recovery.\nTo list recoverable projects, use `GET /projects?recoverable=true`.\n", + "tags": [ + "Project" + ], + "operationId": "recoverProject", + "x-stability-level": "beta", + "responses": { + "200": { + "description": "Returned the recovered project", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectRecoverResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/GeneralError" + } + } + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/neon-4c6b3be4.json b/plugins/openapi/testdata/neon-4c6b3be4.json new file mode 100644 index 0000000..79a0612 --- /dev/null +++ b/plugins/openapi/testdata/neon-4c6b3be4.json @@ -0,0 +1,104 @@ +{ + "openapi": "3.0.3", + "servers": [ + { + "url": "https://console.neon.tech/api/v2" + } + ], + "info": { + "title": "Neon API", + "description": "The Neon API allows you to access and manage Neon programmatically. You can use the Neon API to manage API keys, projects, branches, compute endpoints, databases, roles, and operations. For information about these features, refer to the [Neon documentation](https://neon.com/docs/manage/overview/).\n\nYou can run Neon API requests from this API reference using the **Try It** feature. Enter your API key as a **Bearer** token in the **Authorization** section of the page.\n\nYou can create and manage API keys in the Neon Console. See [Manage API keys](https://neon.com/docs/manage/api-keys/) for instructions.", + "version": "v2", + "license": { + "name": "Proprietary" + } + }, + "paths": { + "/projects/{project_id}/recover": { + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The Neon project ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + } + ], + "post": { + "summary": "Recover a deleted project", + "description": "Recovers a deleted project within the 7-day deletion recovery period.\nRestores branches, endpoints, settings, and connection strings.\nSome integrations require manual reconfiguration after recovery.\nTo list recoverable projects, use `GET /projects?recoverable=true`.\n", + "tags": [ + "Project" + ], + "operationId": "recoverProject", + "x-stability-level": "beta", + "responses": { + "200": { + "description": "Returned the recovered project", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProjectRecoverResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/GeneralError" + } + } + } + }, + "/projects/{project_id}/branches/{branch_id}/recover": { + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The Neon project ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + }, + { + "name": "branch_id", + "in": "path", + "description": "The branch ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + } + ], + "post": { + "summary": "Recover a deleted branch", + "description": "Recovers a deleted branch within the 7-day deletion recovery period.\nThe branch must have been soft deleted and not yet permanently deleted.\nRecovery restores the branch and its endpoints to an idle state.\nConnection strings remain valid after recovery.\nTTL branches become non-TTL branches after recovery.\n\nTo list deleted branches available for recovery, use `GET /projects/{project_id}/branches?include_deleted=true`.\n", + "tags": [ + "Branch" + ], + "operationId": "recoverProjectBranch", + "x-stability-level": "beta", + "responses": { + "200": { + "description": "Recovered the specified branch", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BranchRecoverResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/GeneralError" + } + } + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/neon-5c57d009.json b/plugins/openapi/testdata/neon-5c57d009.json new file mode 100644 index 0000000..3c4b09d --- /dev/null +++ b/plugins/openapi/testdata/neon-5c57d009.json @@ -0,0 +1,115 @@ +{ + "openapi": "3.0.3", + "servers": [ + { + "url": "https://console.neon.tech/api/v2" + } + ], + "info": { + "title": "Neon API", + "description": "The Neon API is the management API for Neon. Use it to provision, configure, and manage resources such as projects, branches, databases, roles, functions, and object storage.\n\nSee the [Neon API reference](https://neon.com/docs/reference/api) for details, and [Manage API keys](https://neon.com/docs/manage/api-keys/) to create and use API keys.", + "version": "v2", + "license": { + "name": "Proprietary" + } + }, + "paths": { + "/projects/{project_id}/auth/email_server": { + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The Neon project ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + } + ], + "get": { + "summary": "Retrieve email server configuration", + "description": "Deprecated. Use `/projects/{project_id}/branches/{branch_id}/auth/email_provider` instead. Removal scheduled for March 1, 2026.\n", + "tags": [ + "Auth (legacy)" + ], + "deprecated": true, + "x-sunset": "2026-03-01", + "operationId": "getNeonAuthEmailServer", + "responses": { + "200": { + "description": "Returns the email server configuration for the Neon Auth", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NeonAuthEmailServerConfigResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/GeneralError" + } + } + } + }, + "/projects/{project_id}/branches/{branch_id}/auth/send_test_email": { + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The Neon project ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + }, + { + "name": "branch_id", + "in": "path", + "description": "The Neon branch ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + } + ], + "post": { + "summary": "Send test email", + "description": "Sends a test email using the configured email server settings to verify SMTP connectivity and credentials.\nThe request body must include the SMTP server settings\n(`host`, `port`, `username`, `password`, `sender_email`, `sender_name`) and the `recipient_email` address.\n", + "tags": [ + "Auth" + ], + "x-stability-level": "beta", + "operationId": "sendNeonAuthTestEmail", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SendNeonAuthTestEmailRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Response with the result of the test email send", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SendNeonAuthTestEmailResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/GeneralError" + } + } + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/neon-93b93dc9.json b/plugins/openapi/testdata/neon-93b93dc9.json new file mode 100644 index 0000000..5c6e9c6 --- /dev/null +++ b/plugins/openapi/testdata/neon-93b93dc9.json @@ -0,0 +1,175 @@ +{ + "openapi": "3.0.3", + "servers": [ + { + "url": "https://console.neon.tech/api/v2" + } + ], + "info": { + "title": "Neon API", + "description": "The Neon API is the management API for Neon. Use it to provision, configure, and manage resources such as projects, branches, databases, roles, functions, and object storage.\n\nSee the [Neon API reference](https://neon.com/docs/reference/api) for details, and [Manage API keys](https://neon.com/docs/manage/api-keys/) to create and use API keys.", + "version": "v2", + "license": { + "name": "Proprietary" + } + }, + "paths": { + "/projects/{project_id}/auth/email_server": { + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The Neon project ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + } + ], + "get": { + "summary": "Retrieve email server configuration", + "description": "Deprecated. Use `/projects/{project_id}/branches/{branch_id}/auth/email_provider` instead. Removal scheduled for March 1, 2026.\n", + "tags": [ + "Auth (legacy)" + ], + "deprecated": true, + "x-sunset": "2026-03-01", + "operationId": "getNeonAuthEmailServer", + "responses": { + "200": { + "description": "Returns the email server configuration for the Neon Auth", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NeonAuthEmailServerConfigResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/GeneralError" + } + } + } + }, + "/projects/{project_id}/branches/{branch_id}/auth/send_test_email": { + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The Neon project ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + }, + { + "name": "branch_id", + "in": "path", + "description": "The Neon branch ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + } + ], + "post": { + "summary": "Send test email", + "description": "Sends a test email using the SMTP server settings supplied in the request body to verify connectivity and credentials.\nThe request body must include the full SMTP server settings\n(`host`, `port`, `username`, `password`, `sender_email`, `sender_name`) and the `recipient_email` address.\n\nDeprecated: to test a branch's already-saved configuration, use `sendNeonAuthEmailProviderTest`, which\nreuses the stored SMTP password server-side so the caller never has to re-supply (or be able to read) it.\nThis endpoint remains available for testing an unsaved full configuration and for non-Better-Auth providers.\n", + "deprecated": true, + "x-sunset": "2027-02-28", + "tags": [ + "Auth" + ], + "x-stability-level": "beta", + "operationId": "sendNeonAuthTestEmail", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SendNeonAuthTestEmailRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Response with the result of the test email send", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SendNeonAuthTestEmailResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/GeneralError" + } + } + } + }, + "/projects/{project_id}/branches/{branch_id}/auth/email_provider/test": { + "parameters": [ + { + "name": "project_id", + "in": "path", + "description": "The Neon project ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + }, + { + "name": "branch_id", + "in": "path", + "description": "The Neon branch ID", + "required": true, + "schema": { + "type": "string", + "pattern": "^[a-z0-9-]{1,60}$" + } + } + ], + "post": { + "summary": "Send test email using the saved email provider", + "description": "Sends a test email using the branch's already-saved custom SMTP configuration. Only the\n`recipient_email` is provided \u2014 the stored SMTP settings and password are used server-side,\nso the caller does not need to re-supply (or be able to read) the password. This avoids the\nGET response's masked password being sent back, which would fail SMTP authentication.\n\nRequires a configured custom SMTP provider on a Better Auth integration. A shared provider,\na missing configuration, or a non-Better-Auth integration is rejected.\n", + "tags": [ + "Auth" + ], + "x-stability-level": "beta", + "operationId": "sendNeonAuthEmailProviderTest", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SendNeonAuthEmailProviderTestRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Response with the result of the test email send", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SendNeonAuthTestEmailResponse" + } + } + } + }, + "default": { + "$ref": "#/components/responses/GeneralError" + } + } + } + } + } +} \ No newline at end of file diff --git a/plugins/openapi/testdata/neon-api-client-2.7.2.yaml b/plugins/openapi/testdata/neon-api-client-2.7.2.yaml new file mode 100644 index 0000000..728c118 --- /dev/null +++ b/plugins/openapi/testdata/neon-api-client-2.7.2.yaml @@ -0,0 +1,295 @@ +openapi: 3.0.3 +servers: +- url: https://console.neon.tech/api/v2 +info: + title: Neon API + version: v2 + license: + name: Proprietary +paths: + /consumption_history/account: + get: + summary: Retrieve account consumption metrics (legacy plans) + description: | + Retrieves consumption metrics for Scale and Enterprise plan accounts, and for legacy Scale, Business, and Enterprise plan accounts. + Consumption history begins at the time the account was upgraded to a supported plan. + + **Deprecated.** Use `GET /consumption_history/projects` (`getConsumptionHistoryPerProject`) + or `GET /consumption_history/v2/projects` (`getConsumptionHistoryPerProjectV2`) instead. + deprecated: true + x-sunset: "2026-06-01" + tags: + - Consumption + operationId: getConsumptionHistoryPerAccount + parameters: + - name: from + description: | + Specify the start `date-time` for the consumption period. + The `date-time` value is rounded according to the specified `granularity`. + For example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`. + The specified `date-time` value must respect the specified granularity: + - For `hourly`, consumption metrics are limited to the last 168 hours. + - For `daily`, consumption metrics are limited to the last 60 days. + - For `monthly`, consumption metrics are limited to the past year. + + The consumption history is available starting from `March 1, 2024, at 00:00:00 UTC`. + in: query + schema: + type: string + format: date-time + required: true + - name: to + description: | + Specify the end `date-time` for the consumption period. + The `date-time` value is rounded according to the specified granularity. + For example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`. + The specified `date-time` value must respect the specified granularity: + - For `hourly`, consumption metrics are limited to the last 168 hours. + - For `daily`, consumption metrics are limited to the last 60 days. + - For `monthly`, consumption metrics are limited to the past year. + in: query + schema: + type: string + format: date-time + required: true + - name: granularity + description: | + Specify the granularity of consumption metrics. + Hourly, daily, and monthly metrics are available for the last 168 hours, 60 days, + and 1 year, respectively. + in: query + schema: + $ref: "#/components/schemas/ConsumptionHistoryGranularity" + required: true + - name: org_id + description: | + Specify the organization for which the consumption metrics should be returned. + If this parameter is not provided, the endpoint will return the metrics for the + authenticated user's account. + in: query + schema: + type: string + pattern: "^[a-z0-9-]{1,60}$" + - name: include_v1_metrics + description: | + The field is deprecated. Please use `metrics` instead. + If `metrics` is specified, this field is ignored. + Include metrics utilized in previous pricing models. + - **data_storage_bytes_hour**: The sum of the maximum observed storage values for each hour + for each project, which never decreases. + in: query + deprecated: true + schema: + type: boolean + - name: metrics + description: | + Specify a list of metrics to include in the response. + If omitted, active_time, compute_time, written_data, synthetic_storage_size are returned. + Possible values: + - `active_time_seconds` + - `compute_time_seconds` + - `written_data_bytes` + - `synthetic_storage_size_bytes` + - `data_storage_bytes_hour` + + A list of metrics can be specified as an array of parameter values or as a comma-separated list in a single parameter value. + - As an array of parameter values: `metrics=cpu_seconds&metrics=ram_bytes` + - As a comma-separated list in a single parameter value: `metrics=cpu_seconds,ram_bytes` + in: query + schema: + $ref: "#/components/schemas/ConsumptionHistoryQueryMetrics" + responses: + 200: + description: Returned consumption metrics for the Neon account + content: + application/json: + schema: + $ref: "#/components/schemas/ConsumptionHistoryPerAccountResponse" + 403: + description: This endpoint is not available. It is only supported for + Scale, Business, and Enterprise plan accounts. + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + 404: + description: Account is not a member of the organization specified by + `org_id`. + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + 406: + description: | + The specified `date-time` range is outside the boundaries of the specified `granularity`. + Adjust your `from` and `to` values or select a different `granularity`. + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + 429: + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + default: + $ref: "#/components/responses/GeneralError" + /consumption_history/projects: + get: + summary: Retrieve project consumption metrics (legacy plans) + description: | + Retrieves consumption metrics for Scale, Business, and Enterprise plan projects. History begins at the time of upgrade. + Results are ordered by time in ascending order (oldest to newest). + Issuing a call to this API does not wake a project's compute endpoint. + tags: + - Consumption + operationId: getConsumptionHistoryPerProject + parameters: + - name: cursor + description: Specify the cursor value from the previous response to get + the next batch of projects. + in: query + schema: + type: string + - name: limit + description: Specify a value from 1 to 100 to limit number of projects + in the response. + in: query + schema: + type: integer + minimum: 1 + default: 10 + maximum: 100 + - name: project_ids + description: | + Specify a list of project IDs to filter the response. + If omitted, the response will contain all projects. + A list of project IDs can be specified as an array of parameter values or as a comma-separated list in a single parameter value. + - As an array of parameter values: `project_ids=cold-poetry-09157238%20&project_ids=quiet-snow-71788278` + - As a comma-separated list in a single parameter value: `project_ids=cold-poetry-09157238,quiet-snow-71788278` + in: query + schema: + type: array + items: + pattern: "^([a-z0-9-]{1,60}(,[a-z0-9-]{1,60}){0,99})?$" + type: string + minItems: 0 + maxItems: 100 + - name: from + description: | + Specify the start `date-time` for the consumption period. + The `date-time` value is rounded according to the specified `granularity`. + For example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`. + The specified `date-time` value must respect the specified `granularity`: + - For `hourly`, consumption metrics are limited to the last 168 hours. + - For `daily`, consumption metrics are limited to the last 60 days. + - For `monthly`, consumption metrics are limited to the last year. + + The consumption history is available starting from `March 1, 2024, at 00:00:00 UTC`. + in: query + schema: + type: string + format: date-time + required: true + - name: to + description: | + Specify the end `date-time` for the consumption period. + The `date-time` value is rounded according to the specified granularity. + For example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`. + The specified `date-time` value must respect the specified `granularity`: + - For `hourly`, consumption metrics are limited to the last 168 hours. + - For `daily`, consumption metrics are limited to the last 60 days. + - For `monthly`, consumption metrics are limited to the last year. + in: query + schema: + type: string + format: date-time + required: true + - name: granularity + description: | + Specify the granularity of consumption metrics. + Hourly, daily, and monthly metrics are available for the last 168 hours, 60 days, + and 1 year, respectively. + in: query + schema: + $ref: "#/components/schemas/ConsumptionHistoryGranularity" + required: true + - name: org_id + description: | + Specify the organization for which the project consumption metrics should be returned. + If this parameter is not provided, the endpoint will return the metrics for the + authenticated user's projects. + in: query + schema: + type: string + pattern: "^[a-z0-9-]{1,60}$" + - name: include_v1_metrics + description: | + The field is deprecated. Please use `metrics` instead. + If `metrics` is specified, this field is ignored. + Include metrics utilized in previous pricing models. + - **data_storage_bytes_hour**: The sum of the maximum observed storage values for each hour, + which never decreases. + in: query + deprecated: true + schema: + type: boolean + - name: metrics + description: | + Specify a list of metrics to include in the response. + If omitted, active_time, compute_time, written_data, synthetic_storage_size are returned. + Possible values: + - `active_time_seconds` + - `compute_time_seconds` + - `written_data_bytes` + - `synthetic_storage_size_bytes` + - `data_storage_bytes_hour` + - `logical_size_bytes` + - `logical_size_bytes_hour` + + A list of metrics can be specified as an array of parameter values or as a comma-separated list in a single parameter value. + - As an array of parameter values: `metrics=cpu_seconds&metrics=ram_bytes` + - As a comma-separated list in a single parameter value: `metrics=cpu_seconds,ram_bytes` + in: query + schema: + $ref: "#/components/schemas/ConsumptionHistoryQueryMetrics" + responses: + 200: + description: Returned project consumption metrics for the Neon account + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ConsumptionHistoryPerProjectResponse" + - $ref: "#/components/schemas/PaginationResponse" + 403: + description: This endpoint is not available. It is only supported with + Scale, Business, and Enterprise plan accounts. + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + 404: + description: Account is not a member of the organization specified by + `org_id`. + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + 406: + description: | + The specified `date-time` range is outside the boundaries of the specified `granularity`. + Adjust your `from` and `to` values or select a different `granularity`. + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + 429: + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + default: + $ref: "#/components/responses/GeneralError" diff --git a/plugins/openapi/testdata/neon-api-client-2.7.3.yaml b/plugins/openapi/testdata/neon-api-client-2.7.3.yaml new file mode 100644 index 0000000..98b70f2 --- /dev/null +++ b/plugins/openapi/testdata/neon-api-client-2.7.3.yaml @@ -0,0 +1,167 @@ +openapi: 3.0.3 +servers: +- url: https://console.neon.tech/api/v2 +info: + title: Neon API + version: v2 + license: + name: Proprietary +paths: + /consumption_history/projects: + get: + summary: Retrieve project consumption metrics (legacy plans) + description: | + Retrieves consumption metrics for Scale, Business, and Enterprise plan projects. History begins at the time of upgrade. + Results are ordered by time in ascending order (oldest to newest). + Issuing a call to this API does not wake a project's compute endpoint. + tags: + - Consumption + operationId: getConsumptionHistoryPerProject + parameters: + - name: cursor + description: Specify the cursor value from the previous response to get + the next batch of projects. + in: query + schema: + type: string + - name: limit + description: Specify a value from 1 to 100 to limit number of projects + in the response. + in: query + schema: + type: integer + minimum: 1 + default: 10 + maximum: 100 + - name: project_ids + description: | + Specify a list of project IDs to filter the response. + If omitted, the response will contain all projects. + A list of project IDs can be specified as an array of parameter values or as a comma-separated list in a single parameter value. + - As an array of parameter values: `project_ids=cold-poetry-09157238%20&project_ids=quiet-snow-71788278` + - As a comma-separated list in a single parameter value: `project_ids=cold-poetry-09157238,quiet-snow-71788278` + in: query + schema: + type: array + items: + pattern: "^([a-z0-9-]{1,60}(,[a-z0-9-]{1,60}){0,99})?$" + type: string + minItems: 0 + maxItems: 100 + - name: from + description: | + Specify the start `date-time` for the consumption period. + The `date-time` value is rounded according to the specified `granularity`. + For example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`. + The specified `date-time` value must respect the specified `granularity`: + - For `hourly`, consumption metrics are limited to the last 168 hours. + - For `daily`, consumption metrics are limited to the last 60 days. + - For `monthly`, consumption metrics are limited to the last year. + + The consumption history is available starting from `March 1, 2024, at 00:00:00 UTC`. + in: query + schema: + type: string + format: date-time + required: true + - name: to + description: | + Specify the end `date-time` for the consumption period. + The `date-time` value is rounded according to the specified granularity. + For example, `2024-03-15T15:30:00Z` for `daily` granularity will be rounded to `2024-03-15T00:00:00Z`. + The specified `date-time` value must respect the specified `granularity`: + - For `hourly`, consumption metrics are limited to the last 168 hours. + - For `daily`, consumption metrics are limited to the last 60 days. + - For `monthly`, consumption metrics are limited to the last year. + in: query + schema: + type: string + format: date-time + required: true + - name: granularity + description: | + Specify the granularity of consumption metrics. + Hourly, daily, and monthly metrics are available for the last 168 hours, 60 days, + and 1 year, respectively. + in: query + schema: + $ref: "#/components/schemas/ConsumptionHistoryGranularity" + required: true + - name: org_id + description: | + Specify the organization for which the project consumption metrics should be returned. + If this parameter is not provided, the endpoint will return the metrics for the + authenticated user's projects. + in: query + schema: + type: string + pattern: "^[a-z0-9-]{1,60}$" + - name: include_v1_metrics + description: | + The field is deprecated. Please use `metrics` instead. + If `metrics` is specified, this field is ignored. + Include metrics utilized in previous pricing models. + - **data_storage_bytes_hour**: The sum of the maximum observed storage values for each hour, + which never decreases. + in: query + deprecated: true + schema: + type: boolean + - name: metrics + description: | + Specify a list of metrics to include in the response. + If omitted, active_time, compute_time, written_data, synthetic_storage_size are returned. + Possible values: + - `active_time_seconds` + - `compute_time_seconds` + - `written_data_bytes` + - `synthetic_storage_size_bytes` + - `data_storage_bytes_hour` + - `logical_size_bytes` + - `logical_size_bytes_hour` + + A list of metrics can be specified as an array of parameter values or as a comma-separated list in a single parameter value. + - As an array of parameter values: `metrics=cpu_seconds&metrics=ram_bytes` + - As a comma-separated list in a single parameter value: `metrics=cpu_seconds,ram_bytes` + in: query + schema: + $ref: "#/components/schemas/ConsumptionHistoryQueryMetrics" + responses: + 200: + description: Returned project consumption metrics for the Neon account + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ConsumptionHistoryPerProjectResponse" + - $ref: "#/components/schemas/PaginationResponse" + 403: + description: This endpoint is not available. It is only supported with + Scale, Business, and Enterprise plan accounts. + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + 404: + description: Account is not a member of the organization specified by + `org_id`. + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + 406: + description: | + The specified `date-time` range is outside the boundaries of the specified `granularity`. + Adjust your `from` and `to` values or select a different `granularity`. + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + 429: + description: Too many requests + content: + application/json: + schema: + $ref: "#/components/schemas/GeneralError" + default: + $ref: "#/components/responses/GeneralError" diff --git a/providers/README.md b/providers/README.md index 9e5821f..c1b723c 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` | +| [neon.md](neon.md) | `neon` | `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/neon.md b/providers/neon.md new file mode 100644 index 0000000..15bb787 --- /dev/null +++ b/providers/neon.md @@ -0,0 +1,54 @@ +# Neon (`neon`) + +## What it watches + +The Neon API (`console.neon.tech/api/v2`), the management API for Neon projects, branches, computes, databases and roles: operations Neon 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.Neon`. + +## Why this source + +- **Source:** `packages/sdk/spec/neon-openapi.json` in [neondatabase/neon-pkgs](https://github.com/neondatabase/neon-pkgs), pinned to the commit that last changed it (`https://raw.githubusercontent.com/neondatabase/neon-pkgs//packages/sdk/spec/neon-openapi.json`). The newest such commit comes from the GitHub commits API. Checked on 2026-11-19. +- **Why this one:** + - It's Neon's own spec, a copy of the one Neon publishes for its API, kept in Neon's own repo. A daily job in the repo ("SDK Spec Drift") pulls `https://neon.com/api_spec/release/v2.json` and fails when it differs from the committed copy; a maintainer then commits the new one. + - It marks deprecations with the `deprecated` flag, and the description says why or until when. + - There are 23 versions from 2026-06-24 to 2026-11-17, and a commit can be cited and replayed. +- **Alternatives considered:** + - **`https://neon.com/api_spec/release/v2.json`.** The same spec served live, but it has no versions to pin, cite or replay. + - **The npm package `@neondatabase/api-client`,** which ships the spec as YAML in each release. `@neon/sdk` succeeded it (neon-pkgs's README calls it the "successor to `@neondatabase/api-client`"), and there's been no release since 2.7.3 on 2026-07-01. + - **The [changelog](https://neon.com/docs/changelog)** (RSS at `https://neon.com/docs/changelog/rss.xml`). It's a weekly digest of everything Neon shipped, with Postgres versions, Console features and AI models in the same post as an API endpoint's deprecation. It does name some API changes ("The deprecated `GET /consumption_history/account` endpoint has been removed.", 2026-06-19), but as prose in a digest, not something to read reliably. + - **The SDKs** (`@neon/sdk`, `@neondatabase/serverless`, the `neon-api` Python package). Their changelogs don't list removed API operations in a form to read. +- **Quote:** "Deprecated: to test a branch's already-saved configuration, use `sendNeonAuthEmailProviderTest`" (`POST /projects/{project_id}/branches/{branch_id}/auth/send_test_email`, deprecated in the spec on 2026-08-23) + +## How the provider announces changes + +- **Operations are named by the path a caller sends,** `POST /api/v2/projects/…`: the spec's server is `https://console.neon.tech/api/v2` and its paths leave out `/api/v2`, so the adapter moves it into the paths (as Sentry's does with `/api/0`). Quotes cite the spec as published. If Neon ever moves `/api/v2` between the server and the paths, the operations stay the same, rather than every deprecated one reading as removed. +- **No API version beyond `/api/v2`.** `info.version` is `v2` in all 23 commits, so the event's `version` is the date of the spec commit, the closest thing to the API version a change arrived in. +- **The spec changes about once a week**, mostly new operations (144 operations on 2026-06-24, 194 on 2026-11-17). +- **Deprecations use the flag.** In all 23 commits no operation is described as deprecated without it. Two unflagged operations deprecate a parameter in words (`include_v1_metrics` on `GET /consumption_history/projects`, and `name` on `POST …/snapshots/{snapshot_id}/restore`); those are parameter deprecations, not operation ones, so they make no event. Each flagged operation also has an `x-sunset` date, and most descriptions say "Removal scheduled for " or "use X instead". +- **Sunset dates aren't removal dates.** On 2026-11-17, 14 operations say "Removal scheduled for March 1, 2026" (`x-sunset` 2026-03-01) and one "Removal scheduled for July 1, 2026", and all 15 are still in the spec, the live one included (checked 2026-11-19). +- **The changelog announces API deprecations and removals in prose:** `GET /consumption_history/account` was "deprecated, with a planned sunset of June 1, 2026" (2026-04-03) and "has been removed" (2026-06-19). + +## 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 Neon's reason and its `x-sunset` date are in the excerpt. + - **Removals (breaking):** an operation that leaves the spec after the previous spec had marked it deprecated. +- **Matches operations by path template,** so a renamed path parameter isn't a removal. None was renamed in the history. +- **Ignores everything else:** + - **Removals of operations that were never deprecated.** One operation left the spec in its history, unmarked: `POST /projects/{project_id}/branches/{branch_id}/recover`, on 2026-08-09. neon-pkgs's own PR for it (#408) found "The endpoint was not removed from the API. It was removed from the published spec": it still routes. + - **`x-sunset` dates and "Removal scheduled" words:** quoted in the deprecation's excerpt, but not events of their own, since the operations outlive them. + - **Request and response property changes, and new operations.** +- **History:** over the 23 commits this keeps 1 event: the deprecation of `POST /projects/{project_id}/branches/{branch_id}/auth/send_test_email` (beta) on 2026-08-23. The other 15 deprecated operations were already flagged in the first commit. +- **Replays** a historical pair (`Replay`, from `5c57d009` to `93b93dc9`) and recreates that deprecation (the golden test). The drop test replays `4c6b3be4` to `4497de89`, the `recover` removal. +- **A kept removal:** none happened in neon-pkgs's history, so a test replays the same spec from `@neondatabase/api-client` 2.7.2 to 2.7.3 (a different source, used only for this test): `GET /consumption_history/account`, deprecated and then removed, the removal Neon's changelog announced. That's one breaking event. + +## Known gaps + +- **Removals Neon didn't mark first aren't events,** even if the endpoint really went away. +- **A sunset date that passes isn't an event.** The 15 operations past their "Removal scheduled" date are reported once, when they were deprecated, and again only if they leave the spec. +- **Lag.** neon-pkgs commits the spec when someone acts on the drift check, days after the live spec changes. On 2026-11-19 the live spec had one operation more than the newest commit. +- **History before 2026-06-24** isn't in neon-pkgs, so deprecations and removals before then (`GET /consumption_history/account`, removed by 2026-06-19) aren't replayable from this source. +- **Only the management API is covered,** not the serverless driver (`@neondatabase/serverless`) or the Data API. +- **Two spec commits on one day would share a `version`.** It hasn't happened in the history. +- **The patch-it client needs `neon` in its list of date-versioned APIs.** The events' `version` is a date (`2026-08-23`), because the API has no version; without the entry, the client reads it as a package version and can't place these events. That list is in the client used by patch-it's hosted ingestion service, not in this repo.