From f0e2de5a3e3cb0f0bc38a35fe4ae7c68bd5d74df Mon Sep 17 00:00:00 2001 From: Alex Gusev Date: Wed, 27 May 2026 12:41:59 +0600 Subject: [PATCH] Prepare 2.0.0 release --- CHANGELOG.md | 53 ++++++++++++++------------------------ README.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b360e09..3fe64da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,56 +1,43 @@ -## 2.0.0 +## 2.0.0 (May 28, 2026) BREAKING CHANGES: -* Target REST API v0.7 (previously v0.5) +* Target REST API v0.7 (previously v0.5); remove the `APIv05` and `APIv06` constants +* Minimum Go version is now 1.25 +* Throttled requests no longer retry by default — automatic retries are now opt-in via `ucare.Config.Retry` +* `file.Service.Info()` now takes `*file.InfoParams` to pass optional `include` query parameters +* `webhook.Service.Delete()` now deletes by webhook ID instead of by target URL +* Remove `RecognitionInfo` field from `file.Info` — use `AppData` instead * Remove `ImageInfo` and `VideoMeta` fields from `file.BasicFileInfo` — use `ContentInfo.Image` and `ContentInfo.Video` -* Remove `RecognitionInfo` field from `file.Info` — use `AppData` -* Add `Metadata` and `AppData` fields to `file.Info` -* Remove `group.Store()` method (endpoint removed in v0.7) * Remove `file.Copy()` method and `file.CopyParams` type — use `LocalCopy()` and `RemoteCopy()` +* Remove `group.Store()` method (endpoint removed in v0.7) * Remove `file.OrderBySizeAsc` and `file.OrderBySizeDesc` constants (not supported in v0.7) -* Remove `APIv05` and `APIv06` constants -* Change `file.Service.Info()` signature to accept `*file.InfoParams` for optional `include` query parameters -* Change `webhook.Service.Delete()` to delete by webhook ID instead of target URL -* Minimum Go version is now 1.25 -* Throttled requests no longer retry by default — automatic retries are now opt-in via `ucare.Config.Retry` FEATURES: -* Add `projectapi` package for the Project API with bearer token authentication — manage projects, project features, moderation thresholds, meta reference lists, secret keys, and usage metrics -* Add `ucare.NewBearerConfig()` and `ucare.NewBearerClient()` for bearer token authentication used by the Project API -* Add `ucare.ProjectAPIError` type for Project API error responses -* Add typed Project API usage metric constants for `traffic`, `storage`, and `operations` -* Add Project API moderation threshold methods and meta reference methods for MIME types and moderation categories -* Add `addon` package for Addons API execution and status polling -* Add typed addon params for Remove.bg and ClamAV requests +* Add `projectapi` package for the Project API, with bearer token authentication via `ucare.NewBearerConfig()` and `ucare.NewBearerClient()` — manage projects, project features, secret keys, usage metrics, moderation thresholds, and meta reference lists for MIME types and moderation categories +* Add `addon` package for Addons API execution and status polling, with typed params for Remove.bg and ClamAV requests * Add `metadata` package with file metadata CRUD operations +* Add `upload.Service.Upload()` for automatic direct-vs-multipart upload selection, with metadata support across direct, multipart, from-URL, and unified uploads +* Resolve a per-project CDN base URL automatically when `ucare.Config.CDNBase` is empty (overridable with an explicit absolute URL), and rewrite the scheme/host of API-returned URLs — `file.Info.OriginalFileURL`, `group.Info.CDNLink`, and `upload.GroupInfo.CDNLink` — to point at it while preserving the full path; exposed via the `ucare.ClientCDNBase(Client)` and `ucare.RewriteCDNURL(originalURL, cdnBase)` helpers +* Export structured error types for inspecting HTTP status and detail: `APIError`, `AuthError`, `ThrottleError`, `ValidationError`, `ForbiddenError`, and Project API equivalents `ProjectAPIError`, `ProjectAuthError`, `ProjectForbiddenError` +* Add `ucare.Config.Retry` and `RetryConfig` for configurable throttling retries +* Add `Metadata` and `AppData` fields to `file.Info`, plus `file.InfoParams.Include` and `file.ListParams.Include` for requesting `include=appdata` * Add `group.Delete()` for deleting group metadata without deleting files +* Add `conversion.Params.SaveInGroup` to persist multi-page document conversion output as a file group, and `conversion.BuildDocumentPath()` / `conversion.BuildVideoPath()` helpers for constructing conversion paths * Add webhook event constants for `file.stored`, `file.deleted`, `file.info_updated`, and deprecated `file.infected` -* Add `ucare.Config.Retry` and `RetryConfig` for configurable throttling retries -* Add `upload.Service.Upload()` for automatic direct-vs-multipart upload selection -* Add upload metadata support for direct, multipart, from-URL, and unified uploads -* Add `file.InfoParams.Include` and `file.ListParams.Include` for `include=appdata` -* Add `conversion.Params.SaveInGroup` for document conversions that should persist image output as a file group -* Add `conversion.BuildDocumentPath()` and `conversion.BuildVideoPath()` helpers for constructing conversion paths -* Export structured API error types: `APIError`, `AuthError`, `ThrottleError`, `ValidationError`, and `ForbiddenError` -* Automatic per-project CDN base URL when `ucare.Config.CDNBase` is empty, with explicit absolute URL override support -* Apply resolved CDN base to API-returned URLs: `file.Info.OriginalFileURL`, `group.Info.CDNLink`, and `upload.GroupInfo.CDNLink` have their scheme/host rewritten to point at the configured CDN while preserving the full path (e.g. `/{uuid}/pineapple.jpg`) -* Export `ucare.ClientCDNBase(Client)` and `ucare.RewriteCDNURL(originalURL, cdnBase)` helpers +* Add typed Project API usage metric constants for `traffic`, `storage`, and `operations` IMPROVEMENTS: * Add `UserAgent` field to `ucare.Config` for custom agent identification +* Throttle retries now use the server `Retry-After` when present, falling back to exponential backoff (capped at 30s), respect context cancellation, and cap the effective wait via `MaxWaitSeconds` * Extend form/query encoding to support Upload API metadata fields in `metadata[key]=value` bracket notation * Replace `http.NewRequest` + `WithContext` with `http.NewRequestWithContext` -* Throttle retry loops now respect context cancellation -* Throttle retries use server `Retry-After` when present, falling back to exponential backoff (capped at 30s); `MaxWaitSeconds` caps the effective wait from either source -* Error values now expose HTTP status details for caller inspection * Replace `ioutil` usage with `io` equivalents * Replace `go-env` dependency with `os.Getenv` * Update `stretchr/testify` to v1.10.0 * Update CI: Go 1.25, modern GitHub Actions versions, remove deprecated golint -* Integration tests skip gracefully when credentials are not set * Fix errors in package documentation examples and update public examples for the new `file.Info()` signature ## 1.2.1 (September 1, 2020) @@ -81,7 +68,7 @@ BUG FIXES: BUG FIXES: -* Set default upload ToStore form param value to "auto" +* Set default upload ToStore form param value to "auto" * Change "UPLOADCARE_STORE" upload.FromURL param to "store" according to specs ## 1.1.8 (Apr 22, 2020) @@ -95,7 +82,7 @@ IMPROVEMENTS: BUG FIXES: -* Change ImageInfo.Orientation type to interface{} +* Change ImageInfo.Orientation type to interface{} ## 1.1.6 (Apr 14, 2020) diff --git a/README.md b/README.md index 6a8589c..fe5dc52 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,8 @@ import ( "github.com/uploadcare/uploadcare-go/v2/group" "github.com/uploadcare/uploadcare-go/v2/upload" "github.com/uploadcare/uploadcare-go/v2/conversion" + "github.com/uploadcare/uploadcare-go/v2/metadata" + "github.com/uploadcare/uploadcare-go/v2/addon" "github.com/uploadcare/uploadcare-go/v2/projectapi" ) ``` @@ -58,6 +60,21 @@ if err != nil { } ``` +`NewConfig` accepts additional options: + +```go +conf, err := ucare.NewConfig(creds, + ucare.WithSignBasedAuthentication(), + ucare.WithUserAgent("my-app/1.0.0"), // appended to the default User-Agent + ucare.WithRetry(&ucare.RetryConfig{MaxRetries: 3}), // retry throttled (429) requests; off by default + ucare.WithCDNBase("https://cdn.example.com"), // override the per-project CDN domain +) +``` + +By default the CDN base URL is derived automatically from the public key, and +URLs returned by the API (`file.Info.OriginalFileURL`, `group.Info.CDNLink`, +`upload.GroupInfo.CDNLink`) are rewritten to point at it. + ### Project API client The Project API uses bearer token authentication. Tokens can be obtained @@ -142,6 +159,62 @@ if err != nil { } ``` +`Upload` picks between direct and multipart uploads automatically based on file +size (multipart above 10MB by default) and accepts custom metadata: + +```go +f, err := os.Open("large-video.mp4") +if err != nil { + // handle error +} + +info, err := uploadSvc.Upload(context.Background(), upload.UploadParams{ + Data: f, + Name: f.Name(), + ContentType: "video/mp4", // required for the multipart path (files > 10MB) + Metadata: map[string]string{"source": "import"}, +}) +if err != nil { + // handle error +} +``` + +Working with per-file metadata: + +```go +metaSvc := metadata.NewService(client) + +_, err := metaSvc.Set(context.Background(), fileID, "source", "import") +if err != nil { + // handle error +} + +all, err := metaSvc.List(context.Background(), fileID) +if err != nil { + // handle error +} +fmt.Printf("metadata: %v\n", all) +``` + +Executing an add-on (e.g. background removal) and polling for the result: + +```go +addonSvc := addon.NewService(client) + +exec, err := addonSvc.Execute(context.Background(), addon.AddonRemoveBG, addon.ExecuteParams{ + Target: fileID, +}) +if err != nil { + // handle error +} + +status, err := addonSvc.Status(context.Background(), addon.AddonRemoveBG, exec.RequestID) +if err != nil { + // handle error +} +fmt.Printf("addon status: %s\n", status.Status) +``` + Managing projects via the Project API: ```go