v0.3.2

Highlights

Typed document retrieval

Client.GetDocument now retrieves a single document through the shared authenticated and retrying transport. It accepts the same WithDocumentView option as partial batch retrieval, including DOCUMENT_VIEW_BASIC for metadata-only responses that report contentLengthBytes without downloading document content.

DocumentOption is the shared option type for GetDocument and BatchGetDocumentsPartial. The existing BatchGetOption name remains as a type alias, so existing callers continue to compile unchanged.

The new method rejects invalid document names, unknown views, and malformed top-level null responses before returning a document.

Compatibility

This release is additive and does not contain breaking API changes. The existing BatchGetDocuments, BatchGetDocumentsAll, and BatchGetDocumentsPartial behavior remains unchanged.

v0.3.1

Highlights

Typed GA AnswerQuery support

Client.AnswerQuery now provides typed access to the GA v1 grounded-answer endpoint. The response models include UTF-8 byte-indexed citations and document references that reuse the package's existing Document and DocumentChunk types.

The method rejects nil or blank requests and malformed top-level null responses while preserving API errors for errors.As inspection through the existing request transport.

Partial batch retrieval and document views

BatchGetDocumentsPartial fetches input names in API-sized chunks, preserves input order and duplicate occurrences, and reports document-specific failures positionally without discarding successful results. Fatal request errors retain already completed results and leave later entries explicitly unprocessed.

WithDocumentView selects the API's BASIC, FULL, or CONTENT document views. Existing BatchGetDocuments and BatchGetDocumentsAll signatures and behavior are unchanged.

Compatibility

This release is additive and does not contain breaking API changes.

v0.3.0

Summary

v0.3.0 makes authenticated clients fail closed around credential discovery and request origins, corrects API error classification, and gives NormalizeDocName a strict invalid-input contract.

This release contains PR #21.

Breaking changes

Authenticated requests are origin-bound

• Client.DoAPIRequest, DoGet, and DoJSONPost now require the request URL to share the validated origin of Client.BaseURL.
• Clients returned by NewAuthenticatedHTTPClient and NewADCHTTPClient restrict initial requests and redirects to AuthConfig.AllowedOrigin, which defaults to DefaultV1BaseURL.
• Redirects during Client requests are same-origin-restricted even with a caller-supplied HTTPClient; a custom CheckRedirect callback is chained, not replaced.
• Origins must be canonical, hierarchical ASCII HTTP(S) URLs without userinfo. Request Host overrides are also validated.

Migration: set AuthConfig.AllowedOrigin when a constructor-created authenticated client targets a non-default endpoint. A client used for https://apikeys.googleapis.com, for example, must explicitly allow that origin.

Explicit credential paths are strict

AuthConfig.CredentialsPath is evaluated exactly once and is now an explicit credential source. Missing, unreadable, malformed, or otherwise invalid files return an error instead of falling back to another ADC source.

Migration: omit CredentialsPath when standard platform or metadata-server ADC fallback is desired. Do not pass DefaultCredentialsPath merely to restate the default lookup behavior.

NormalizeDocName rejects invalid URL-like input

Empty or invalid input now returns "". URL-like input must be a hierarchical ASCII HTTP(S) URL without userinfo. Unsupported schemes, opaque URLs, protocol-relative URLs, malformed authorities, bracketed DNS/IPv4 authorities, and Unicode hostnames are rejected. Valid scheme-less host:port paths, including query- or fragment-only forms, and bracketed IPv6 paths remain supported.

For accepted URLs, hostnames are lowercased, default ports are stripped, percent-encoded path segments are preserved rather than decoded, and trailing slashes are removed. Callers that cache or compare normalized names may observe different strings after upgrading.

Migration: check for an empty result before sending the normalized resource name to the API.

APIError.Code is always the HTTP status

APIError.Code now comes from the HTTP response status rather than the JSON error.code field. IsBisectableDocumentError now requires the exact matched pairs 400 + INVALID_ARGUMENT or 404 + NOT_FOUND.

external_account credentials no longer require a quota project

Only authorized_user credentials require a quota project during client construction. external_account credentials can be used without one; when present, their quota_project_id is still honored.

Ambient CLOUDSDK_CONFIG errors are distinguished from absence

When the ADC file under CLOUDSDK_CONFIG exists, its bytes provide both the token source and quota-project metadata. Pure file absence continues to standard ADC discovery; permission failures, non-directory paths, dangling symlinks, malformed credentials, and other read errors are returned.

Additions

• AuthConfig.AllowedOrigin configures the only origin that a constructor-created authenticated client may contact.
• AuthConfig.QuotaProjectID explicitly configures x-goog-user-project and takes precedence over GOOGLE_CLOUD_QUOTA_PROJECT and credential-file metadata.

Fixes and hardening

• Token sources and quota-project metadata are derived from the same credential bytes, avoiding mixed credential sources.
• A custom AuthConfig.TokenSource no longer consults CredentialsPath or ambient credential-file metadata.
• Rejected transport requests close their request bodies without invoking the wrapped transport.
• Nil origins return an error instead of panicking.
• CloseIdleConnections is delegated through the origin and quota-project transports.
• Redirect callbacks are chained and revalidated after callback mutations.
• URL authority validation covers empty and out-of-range ports, non-canonical brackets, IPv6, Unicode case folding, userinfo, opaque URLs, and Request.Host overrides.
• CI asks actions/setup-go for the latest patch release before govulncheck, preventing stale hosted-toolcache versions from reintroducing fixed standard-library vulnerabilities.

Upgrade notes

Consumers upgrading directly from v0.1.x must also apply the context-first API migration documented in the v0.2.0 release notes.

go get github.com/apstndb/developerknowledge-go@v0.3.0

Verification

• go test -race ./...
• go vet ./...
• golangci-lint run
• govulncheck ./...
• GitHub Actions on Go 1.24 and Go 1.25
• Live v1 documents:batchGet: 20 names succeed; 21 names return 400 INVALID_ARGUMENT, so MaxBatchGetDocuments remains 20

Not included

• The open retry-policy expansion and golang.org/x/oauth2 update are not part of this release.

Full diff: v0.2.0...v0.3.0

Release notes updated 2026-07-13 to clarify normalization output and redirect behavior; the v0.3.0 tag is unchanged.

v0.2.0

Breaking changes

Context-first API

Client.Context has been removed. All request methods now take context.Context as their first parameter:

• DoAPIRequest(ctx, method, reqURL, body, contentType)
• DoGet(ctx, reqURL)
• DoJSONPost(ctx, reqURL, body)
• BatchGetDocuments(ctx, names)

Migration for dependents (dkcli, gcp-docs-mirror-tools, spanner-mycli):

1. Remove Client.Context field assignment.
2. Pass ctx as the first argument to every Client method call.
3. If you previously relied on Client.Context for cancellation/timeouts, pass that same context per call instead.

BatchGetDocuments validation

BatchGetDocuments now rejects empty name lists and more than MaxBatchGetDocuments (20) names per call. Use the new BatchGetDocumentsAll helper for larger lists (see below).

New features

• MaxBatchGetDocuments constant — documents the API limit of 20 names per documents:batchGet call.
• BatchGetDocumentsAll(ctx, names) — fetches documents in chunks of MaxBatchGetDocuments while preserving input order.
• Document.ContentLengthBytes — new field mapped from the API's contentLengthBytes.
• Package documentation — added doc.go with godoc for the dkapi package.
• Agent instructions — added AGENTS.md (referenced by CLAUDE.md) documenting module purpose, conventions, and verification commands.
• CI workflow — GitHub Actions runs go test -race, go vet, golangci-lint, and govulncheck on Go 1.24 and 1.25.
• Dependabot — weekly updates for Go modules and GitHub Actions.
• golangci-lint config — .golangci.yml with errcheck, govet, staticcheck, and unused linters.

Fixes

• CLOUDSDK_CONFIG ADC resolution — when CLOUDSDK_CONFIG or GOOGLE_APPLICATION_CREDENTIALS is set, or when the default ADC credentials file exists, token and quota-project metadata are read from that file instead of falling through to metadata-server ADC.
• external_account quota project — ADC now requires a quota project for external_account credentials (in addition to authorized_user), matching authorized_user behavior.
• Bounded error-body reads — CheckResponse limits response body reads to 1 MiB for non-2xx and 429 responses, preventing unbounded memory use on error responses.
• NormalizeDocName hardening — handles full URLs via url.Parse, strips query strings and fragments, removes trailing slashes, accepts uppercase HTTP:///HTTPS:// prefixes, and normalizes empty input to documents/.

Documentation

• README — updated example for context-first API, documents BatchGetDocumentsAll, CLOUDSDK_CONFIG support, bounded error reads, and links to pkg.go.dev.

Dependent repos

Open PRs in dkcli, spanner-mycli, and gcp-docs-mirror-tools that pin pseudo-versions of this module should update to:

go get github.com/apstndb/developerknowledge-go@v0.2.0

Not included

PR #20 (expand retry policy beyond 429-only) remains open and is not part of this release.

v0.1.2

Fix ADC credentials lookup to honor CLOUDSDK_CONFIG when resolving local application_default_credentials.json for quota project metadata.

v0.1.1

Fixes

• Preserve the empty uri field in serialized Document values for dkcli compatibility.
• Parse HTTP-date Retry-After values in addition to delay-seconds.
• Treat any 2xx HTTP response as success.
• Make Client.MaxRetries mean additional retries after the first attempt and add coverage for one-retry behavior.

v0.1.0

Initial release.\n\n- Add API key and ADC authentication helpers.\n- Add quota project handling for local ADC.\n- Add Developer Knowledge API error and rate-limit parsing.\n- Add context-aware request helpers.\n- Add documents:batchGet support.\n- Add shared Document and DocumentChunk response types.\n- Add conservative batch bisection error classification.