files.com 1.1.767 → 1.1.769

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f28911c7269ba7bca7b67e635c974300c1766dffd95239e2755bc3e6fd59309
-  data.tar.gz: 10abf8ff3c46f32c466f3658c2c86b9953771c13664af3665fee10a4108d3cf4
+  metadata.gz: '00813c437bd03f8e8d5f2f33678070fb59d257993674718005d410593edf036e'
+  data.tar.gz: 61dd556a50fd3450fda1aec7187278cfd2638bf2badee307a7fc3983def6dd2d
 SHA512:
-  metadata.gz: a44129f9828a4d647097cb1d86af56940f5402e71c389e6fdc74ba693e3a60f06b4f724201b5a625c5ee13c3768db7daf9f8b2ab31379c66b3a3c35240fbcd1a
-  data.tar.gz: 6337ed3e62e953bd9d51d0da29f2d87079b4b8d0b1408061cc6a571405255f3b3c7247247da48bea29a6c7e473ee98b01889ca731467e4c47dd5c6a8c35d9e12
+  metadata.gz: 96eaaea7de07df44e3cca9b4973f36e745e683e1ed45afadb7f1201535cc268d691311fda5f992b120ef74447a345f309cb85453a23b25cd0278b2d2fd7602c0
+  data.tar.gz: f61bad4e74ca51a96eb9cae670c249015134bb00abbf56eb5f8dd5d701fa4db895ff6ab1c94fa5854f0d5bb29e53c63dbb28d47bc73ca21d74c784eebcf98005

data/Gemfile.lock

@@ -103,4 +103,4 @@ DEPENDENCIES
   rubocop
 
 BUNDLED WITH
-  4.0.12
+  4.0.21

data/README.md

@@ -410,9 +410,9 @@ A user's or group's `workspace_id` identifies the Workspace the account belongs
 | Default Workspace user | Create an `admin` Permission for the user on a Custom Workspace's root folder. | Each Custom Workspace with a root grant. |
 | Default Workspace group | Create an `admin` Permission for the group on a Custom Workspace's root folder. | Every member inherits administration of each Workspace with a root grant. |
 
-`workspace_admin` is not a summary of a user's effective administrative access. A Default Workspace user can administer a Custom Workspace through a direct or group root grant while their `workspace_admin` remains `false`. Groups have no `workspace_admin` field. See [Users](/ruby/resources/user-accounts/users) and [Groups](/ruby/resources/user-accounts/groups) for account fields.
+`workspace_admin` is not a summary of a user's effective administrative access. A Default Workspace user can administer a Custom Workspace through a direct or group root grant while their `workspace_admin` remains `false`. Groups have no `workspace_admin` field. See [Users](https://developers.files.com/ruby/resources/user-accounts/users) and [Groups](https://developers.files.com/ruby/resources/user-accounts/groups) for account fields.
 
-An `admin` grant on the **Custom Workspace root** provides full Workspace Administrator authority over its files, users, groups, Partners, workflows, and integrations. An `admin` grant on a subfolder provides Folder Admin authority over that folder and its descendants; it does not provide Workspace administration. Other permission levels provide their corresponding folder access without Workspace administration. [Permissions](/ruby/resources/user-accounts/permissions) defines the levels.
+An `admin` grant on the **Custom Workspace root** provides full Workspace Administrator authority over its files, users, groups, Partners, workflows, and integrations. An `admin` grant on a subfolder provides Folder Admin authority over that folder and its descendants; it does not provide Workspace administration. Other permission levels provide their corresponding folder access without Workspace administration. [Permissions](https://developers.files.com/ruby/resources/user-accounts/permissions) defines the levels.
 
 Site Administrators manage cross-Workspace assignments to Default Workspace accounts. Workspace Administrators manage accounts and permissions within their own scope. Site Administrators retain access to every Workspace; adding a Workspace grant does not narrow Site Administrator authority. The [product documentation](https://www.files.com/docs/workspaces/workspace-administrators) explains the administrator's operational scope and site-wide controls.
 
@@ -424,7 +424,7 @@ A resource's `workspace_id` request field describes the resource's Workspace mem
 
 Selecting another Workspace with an API key requires a **Full Access key created in the Default Workspace**. A user key follows that user's current access, including group permissions. A site-wide Full Access key created in the Default Workspace has Site Administrator authority in every Workspace. A Files Only key stays in its creation Workspace, even if its user has cross-Workspace access. Any key created in a Custom Workspace stays within that Workspace. Selecting another context with these confined keys is rejected with `bad-request/invalid-workspace-id-header`.
 
-An account belonging to a Custom Workspace is scoped there when it authenticates normally. For a Default Workspace user, explicitly select the intended Workspace for an integration rather than relying on an interactive login preference. [API Keys](/ruby/resources/developers/api-keys) and [Authentication](/ruby/overview/authentication) cover credentials.
+An account belonging to a Custom Workspace is scoped there when it authenticates normally. For a Default Workspace user, explicitly select the intended Workspace for an integration rather than relying on an interactive login preference. [API Keys](https://developers.files.com/ruby/resources/developers/api-keys) and [Authentication](https://developers.files.com/ruby/overview/authentication) cover credentials.
 
 The Files.com Ruby SDK supports workspace scoping by using the `Files.workspace_id` configuration attribute. Scope a single request by passing `workspace_id` in the request options.
 
@@ -442,13 +442,13 @@ Files::Folder.list_for("", {}, workspace_id: 456)
 
 An operations team already represented by a Default Workspace group can administer a Custom Workspace through one root Permission. The group and its members stay in the Default Workspace, so the same team can receive different access in other Workspaces.
 
-First retrieve the target [Workspace](/ruby/resources/settings/workspaces) and [Group](/ruby/resources/user-accounts/groups) IDs as a Site Administrator in Workspace `0`. The examples use Workspace `123`, group `456`, and member user `789`; replace them with your own IDs. Confirm that the group belongs to Workspace `0` and that the intended user is a member.
+First retrieve the target [Workspace](https://developers.files.com/ruby/resources/settings/workspaces) and [Group](https://developers.files.com/ruby/resources/user-accounts/groups) IDs as a Site Administrator in Workspace `0`. The examples use Workspace `123`, group `456`, and member user `789`; replace them with your own IDs. Confirm that the group belongs to Workspace `0` and that the intended user is a member.
 
 Create the Permission using a Default Workspace Full Access site-wide key or a Full Access user key belonging to a Site Administrator. Keep the request context at `0` and use the qualified root path `_/Workspaces/123`. Set `group_id` to the group's ID, `permission` to `admin`, and `recursive` to `true`. Save the returned Permission `id` for later removal. For an individual Default Workspace user, use `user_id` instead of `group_id`.
 
 For a Default Workspace group, a Site Administrator can also select Workspace `123` and use an empty `path` to grant access to its root. The qualified path in Workspace `0` works for both Default Workspace users and groups and keeps the account scope and target Workspace explicit. Appending a subfolder to the path would grant Folder Admin access instead of Workspace Administrator authority.
 
-After the grant, run the request-context example above with the member's own credential and Workspace `123` selected. That member can work with the Workspace's files and perform Workspace Administrator operations, such as managing its users, Partners, and integrations. A Site Administrator's successful request does not establish that the member has the intended access.
+After the grant, make a request as the member, using their own credential with Workspace `123` selected, such as listing that Workspace's root folder. That member can work with the Workspace's files and perform Workspace Administrator operations, such as managing its users, Partners, and integrations. A Site Administrator's successful request does not establish that the member has the intended access.
 
 ```ruby title="Grant group administration"
 require 'files.com'
@@ -463,6 +463,12 @@ grant = Files::Permission.create({
 puts grant.id
 ```
 
+```ruby title="Request as the group member"
+Files::Folder.list_for("", {}, api_key: "YOUR_MEMBER_API_KEY", workspace_id: 123).each do |entry|
+  puts entry.path
+end
+```
+
 ### Permission Inspection and Removal
 
 List the member's Permissions with `user_id` and `include_groups=true` to include grants inherited through group membership. Listing only direct user grants can miss the Permission that provides Workspace administration. In Workspace `0`, the Custom Workspace root appears as `_/Workspaces/123`; in Workspace `123`, paths are relative to that root. Inspect the root path and `permission=admin`, rather than treating the user's `workspace_admin` field as their effective administrative access.
@@ -476,7 +482,7 @@ Group membership maintained through SCIM follows the same rule. A Group Admin al
 Delete the Permission by its returned `id` as the Site Administrator in Workspace `0`. The removal examples use Permission ID `9001`; replace it with the ID returned by your create request. Permissions are created and deleted, rather than updated in place. If narrower folder access is still needed, assign it explicitly; deleting a broad grant does not restore narrower grants it previously replaced.
 
 ```ruby title="Inspect member grants and remove the group grant"
-Files::Permission.list({user_id: "789", include_groups: true}, workspace_id: 0).each do |item|
+Files::Permission.list({user_id: "789", include_groups: true}, workspace_id: 0).auto_paging_each do |item|
   puts [item.path, item.permission, item.group_id].inspect
 end
 Files::Permission.delete(9001, {}, workspace_id: 0)
@@ -772,7 +778,13 @@ Files::FolderAdminPermissionRequiredError -> Files::NotAuthorizedError -> Files:
 Certain API operations return lists of objects. When the number of objects in the list is large,
 the API will paginate the results.
 
-The Files.com Ruby SDK automatically paginates through lists of objects by default.
+The Files.com Ruby SDK provides multiple ways to paginate through lists of objects.
+
+### Automatic Pagination
+
+The `auto_paging_each` method iterates through every object on every page, requesting each page
+only when iteration reaches it. Without a block it returns a lazy enumerator, so methods such as
+`first(10)` request only the pages they need.
 
 ```ruby title="Example Request" hasDataFormatSelector
 begin
@@ -789,6 +801,34 @@ rescue Files::Error => e
 end
 ```
 
+### Manual Pagination
+
+A list operation returns its first page. `each`, and every other `Enumerable` method, covers the
+objects on that page. `has_next_page?` reports whether another page follows, and `next_page`
+requests it. After the last page, `next_page` returns an empty page without making a request.
+
+All pages of a list share one position for `next_page`, so calling it again on an earlier page
+continues after the newest page. `auto_paging_each` keeps its own position: it starts at the page
+you call it on and does not move `next_page`.
+
+```ruby title="Example Request"
+begin
+  page = Files::Folder.list_for(path, per_page: 100)
+  loop do
+    page.each do |file|
+      # Operate on file
+    end
+    break unless page.has_next_page?
+
+    page = page.next_page
+  end
+rescue Files::NotAuthenticatedError => e
+  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
+rescue Files::Error => e
+  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
+end
+```
+
 ## Mock Server
 
 Files.com publishes a mock Files.com API server, which is useful for testing your use of the Files.com

data/_VERSION

@@ -1 +1 @@
-1.1.767
+1.1.769

data/docs/event_record.md

@@ -7,7 +7,7 @@
   "id": 1,
   "workspace_id": 1,
   "event_uuid": "example",
-  "event_type": "example",
+  "event_type": "sync_run.failure.v1",
   "severity": "example",
   "source_type": "example",
   "source_id": 1,
@@ -29,7 +29,7 @@
 * `id` (int64): Event Record ID
 * `workspace_id` (int64): Workspace ID. 0 means the default workspace or site-wide.
 * `event_uuid` (string): Stable event UUID.
-* `event_type` (string): Versioned event type string.
+* `event_type` (string): Versioned event type string. Valid values: `automation_run.canceled.v1`, `automation_run.failure.v1`, `automation_run.failure_will_retry.v1`, `automation_run.partial_failure.v1`, `automation_run.partial_failure_will_retry.v1`, `automation_run.skipped.v1`, `automation_run.success.v1`, `expectation_evaluation.invalid.v1`, `expectation_evaluation.late.v1`, `expectation_evaluation.missing.v1`, `expectation_evaluation.success.v1`, `expectation_incident.acknowledged.v1`, `expectation_incident.open.v1`, `expectation_incident.resolved.v1`, `expectation_incident.snoozed.v1`, `external_event.client_log.failure.v1`, `external_event.client_log.partial_failure.v1`, `external_event.client_log.skipped.v1`, `external_event.client_log.success.v1`, `pending_work_event.failure.v1`, `pending_work_event.partial_failure.v1`, `pending_work_event.skipped.v1`, `pending_work_event.success.v1`, `siem_http_destination_event.failure.v1`, `siem_http_destination_event.partial_failure.v1`, `siem_http_destination_event.skipped.v1`, `siem_http_destination_event.success.v1`, `sso_event.ldap_login.failure.v1`, `sso_event.ldap_login.partial_failure.v1`, `sso_event.ldap_login.skipped.v1`, `sso_event.ldap_login.success.v1`, `sso_event.ldap_sync.failure.v1`, `sso_event.ldap_sync.partial_failure.v1`, `sso_event.ldap_sync.skipped.v1`, `sso_event.ldap_sync.success.v1`, `sso_event.saml_login.failure.v1`, `sso_event.saml_login.partial_failure.v1`, `sso_event.saml_login.skipped.v1`, `sso_event.saml_login.success.v1`, `sync_run.failure.v1`, `sync_run.partial_failure.v1`, `sync_run.skipped.v1`, `sync_run.success.v1`, `user_security_event.lockout.v1`
 * `severity` (string): Event severity.
 * `source_type` (string): Source record type.
 * `source_id` (int64): Source record ID.

data/docs/event_subscription.md

@@ -14,7 +14,7 @@
   "message_only": true,
   "enabled": true,
   "event_types": [
-    "example"
+    "sync_run.failure.v1"
   ],
   "filter": "example",
   "delivery_policy": "example",
@@ -35,7 +35,7 @@
 * `message` (string): Custom message to include in notification emails.
 * `message_only` (boolean): If true, notification email bodies contain only the custom message, omitting event details and the review button. Requires a custom message, defaults to false, and does not affect non-email targets.
 * `enabled` (boolean): Whether this Event Subscription can dispatch events.
-* `event_types` (array(string)): Event type strings matched by this subscription. Blank means all event types.
+* `event_types` (array(string)): Event type strings matched by this subscription. Blank means all event types. Valid values: `automation_run.canceled.v1`, `automation_run.failure.v1`, `automation_run.failure_will_retry.v1`, `automation_run.partial_failure.v1`, `automation_run.partial_failure_will_retry.v1`, `automation_run.skipped.v1`, `automation_run.success.v1`, `expectation_evaluation.invalid.v1`, `expectation_evaluation.late.v1`, `expectation_evaluation.missing.v1`, `expectation_evaluation.success.v1`, `expectation_incident.acknowledged.v1`, `expectation_incident.open.v1`, `expectation_incident.resolved.v1`, `expectation_incident.snoozed.v1`, `external_event.client_log.failure.v1`, `external_event.client_log.partial_failure.v1`, `external_event.client_log.skipped.v1`, `external_event.client_log.success.v1`, `pending_work_event.failure.v1`, `pending_work_event.partial_failure.v1`, `pending_work_event.skipped.v1`, `pending_work_event.success.v1`, `siem_http_destination_event.failure.v1`, `siem_http_destination_event.partial_failure.v1`, `siem_http_destination_event.skipped.v1`, `siem_http_destination_event.success.v1`, `sso_event.ldap_login.failure.v1`, `sso_event.ldap_login.partial_failure.v1`, `sso_event.ldap_login.skipped.v1`, `sso_event.ldap_login.success.v1`, `sso_event.ldap_sync.failure.v1`, `sso_event.ldap_sync.partial_failure.v1`, `sso_event.ldap_sync.skipped.v1`, `sso_event.ldap_sync.success.v1`, `sso_event.saml_login.failure.v1`, `sso_event.saml_login.partial_failure.v1`, `sso_event.saml_login.skipped.v1`, `sso_event.saml_login.success.v1`, `sync_run.failure.v1`, `sync_run.partial_failure.v1`, `sync_run.skipped.v1`, `sync_run.success.v1`, `user_security_event.lockout.v1`
 * `filter` (object): Structured event payload filter.
 * `delivery_policy` (object): Event Subscription delivery policy.
 * `event_target_ids` (array(int64)): Event Target IDs this subscription sends to.
@@ -86,7 +86,7 @@ Files::EventSubscription.create(
   message: "example", 
   message_only: true, 
   enabled: true, 
-  event_types: ["example"], 
+  event_types: ["sync_run.failure.v1"], 
   delivery_policy: "example", 
   event_target_ids: [1]
 )
@@ -102,7 +102,7 @@ Files::EventSubscription.create(
 * `message` (string): Custom message to include in notification emails.
 * `message_only` (boolean): If true, notification email bodies contain only the custom message, omitting event details and the review button. Requires a custom message, defaults to false, and does not affect non-email targets.
 * `enabled` (boolean): Whether this Event Subscription can dispatch events.
-* `event_types` (array(string)): Event type strings matched by this subscription. Blank means all event types.
+* `event_types` (array(string)): Event type strings matched by this subscription. Blank means all event types. Valid values: `automation_run.canceled.v1`, `automation_run.failure.v1`, `automation_run.failure_will_retry.v1`, `automation_run.partial_failure.v1`, `automation_run.partial_failure_will_retry.v1`, `automation_run.skipped.v1`, `automation_run.success.v1`, `expectation_evaluation.invalid.v1`, `expectation_evaluation.late.v1`, `expectation_evaluation.missing.v1`, `expectation_evaluation.success.v1`, `expectation_incident.acknowledged.v1`, `expectation_incident.open.v1`, `expectation_incident.resolved.v1`, `expectation_incident.snoozed.v1`, `external_event.client_log.failure.v1`, `external_event.client_log.partial_failure.v1`, `external_event.client_log.skipped.v1`, `external_event.client_log.success.v1`, `pending_work_event.failure.v1`, `pending_work_event.partial_failure.v1`, `pending_work_event.skipped.v1`, `pending_work_event.success.v1`, `siem_http_destination_event.failure.v1`, `siem_http_destination_event.partial_failure.v1`, `siem_http_destination_event.skipped.v1`, `siem_http_destination_event.success.v1`, `sso_event.ldap_login.failure.v1`, `sso_event.ldap_login.partial_failure.v1`, `sso_event.ldap_login.skipped.v1`, `sso_event.ldap_login.success.v1`, `sso_event.ldap_sync.failure.v1`, `sso_event.ldap_sync.partial_failure.v1`, `sso_event.ldap_sync.skipped.v1`, `sso_event.ldap_sync.success.v1`, `sso_event.saml_login.failure.v1`, `sso_event.saml_login.partial_failure.v1`, `sso_event.saml_login.skipped.v1`, `sso_event.saml_login.success.v1`, `sync_run.failure.v1`, `sync_run.partial_failure.v1`, `sync_run.skipped.v1`, `sync_run.success.v1`, `user_security_event.lockout.v1`
 * `filter` (object): Structured event payload filter.
 * `delivery_policy` (object): Event Subscription delivery policy.
 * `event_target_ids` (array(int64)): Event Target IDs this subscription sends to.
@@ -122,7 +122,7 @@ Files::EventSubscription.update(id,
   message: "example", 
   message_only: true, 
   enabled: true, 
-  event_types: ["example"], 
+  event_types: ["sync_run.failure.v1"], 
   delivery_policy: "example", 
   event_target_ids: [1]
 )
@@ -139,7 +139,7 @@ Files::EventSubscription.update(id,
 * `message` (string): Custom message to include in notification emails.
 * `message_only` (boolean): If true, notification email bodies contain only the custom message, omitting event details and the review button. Requires a custom message, defaults to false, and does not affect non-email targets.
 * `enabled` (boolean): Whether this Event Subscription can dispatch events.
-* `event_types` (array(string)): Event type strings matched by this subscription. Blank means all event types.
+* `event_types` (array(string)): Event type strings matched by this subscription. Blank means all event types. Valid values: `automation_run.canceled.v1`, `automation_run.failure.v1`, `automation_run.failure_will_retry.v1`, `automation_run.partial_failure.v1`, `automation_run.partial_failure_will_retry.v1`, `automation_run.skipped.v1`, `automation_run.success.v1`, `expectation_evaluation.invalid.v1`, `expectation_evaluation.late.v1`, `expectation_evaluation.missing.v1`, `expectation_evaluation.success.v1`, `expectation_incident.acknowledged.v1`, `expectation_incident.open.v1`, `expectation_incident.resolved.v1`, `expectation_incident.snoozed.v1`, `external_event.client_log.failure.v1`, `external_event.client_log.partial_failure.v1`, `external_event.client_log.skipped.v1`, `external_event.client_log.success.v1`, `pending_work_event.failure.v1`, `pending_work_event.partial_failure.v1`, `pending_work_event.skipped.v1`, `pending_work_event.success.v1`, `siem_http_destination_event.failure.v1`, `siem_http_destination_event.partial_failure.v1`, `siem_http_destination_event.skipped.v1`, `siem_http_destination_event.success.v1`, `sso_event.ldap_login.failure.v1`, `sso_event.ldap_login.partial_failure.v1`, `sso_event.ldap_login.skipped.v1`, `sso_event.ldap_login.success.v1`, `sso_event.ldap_sync.failure.v1`, `sso_event.ldap_sync.partial_failure.v1`, `sso_event.ldap_sync.skipped.v1`, `sso_event.ldap_sync.success.v1`, `sso_event.saml_login.failure.v1`, `sso_event.saml_login.partial_failure.v1`, `sso_event.saml_login.skipped.v1`, `sso_event.saml_login.success.v1`, `sync_run.failure.v1`, `sync_run.partial_failure.v1`, `sync_run.skipped.v1`, `sync_run.success.v1`, `user_security_event.lockout.v1`
 * `filter` (object): Structured event payload filter.
 * `delivery_policy` (object): Event Subscription delivery policy.
 * `event_target_ids` (array(int64)): Event Target IDs this subscription sends to.
@@ -174,7 +174,7 @@ event_subscription.update(
   message: "example",
   message_only: true,
   enabled: true,
-  event_types: ["example"],
+  event_types: ["sync_run.failure.v1"],
   delivery_policy: "example",
   event_target_ids: [1]
 )
@@ -191,7 +191,7 @@ event_subscription.update(
 * `message` (string): Custom message to include in notification emails.
 * `message_only` (boolean): If true, notification email bodies contain only the custom message, omitting event details and the review button. Requires a custom message, defaults to false, and does not affect non-email targets.
 * `enabled` (boolean): Whether this Event Subscription can dispatch events.
-* `event_types` (array(string)): Event type strings matched by this subscription. Blank means all event types.
+* `event_types` (array(string)): Event type strings matched by this subscription. Blank means all event types. Valid values: `automation_run.canceled.v1`, `automation_run.failure.v1`, `automation_run.failure_will_retry.v1`, `automation_run.partial_failure.v1`, `automation_run.partial_failure_will_retry.v1`, `automation_run.skipped.v1`, `automation_run.success.v1`, `expectation_evaluation.invalid.v1`, `expectation_evaluation.late.v1`, `expectation_evaluation.missing.v1`, `expectation_evaluation.success.v1`, `expectation_incident.acknowledged.v1`, `expectation_incident.open.v1`, `expectation_incident.resolved.v1`, `expectation_incident.snoozed.v1`, `external_event.client_log.failure.v1`, `external_event.client_log.partial_failure.v1`, `external_event.client_log.skipped.v1`, `external_event.client_log.success.v1`, `pending_work_event.failure.v1`, `pending_work_event.partial_failure.v1`, `pending_work_event.skipped.v1`, `pending_work_event.success.v1`, `siem_http_destination_event.failure.v1`, `siem_http_destination_event.partial_failure.v1`, `siem_http_destination_event.skipped.v1`, `siem_http_destination_event.success.v1`, `sso_event.ldap_login.failure.v1`, `sso_event.ldap_login.partial_failure.v1`, `sso_event.ldap_login.skipped.v1`, `sso_event.ldap_login.success.v1`, `sso_event.ldap_sync.failure.v1`, `sso_event.ldap_sync.partial_failure.v1`, `sso_event.ldap_sync.skipped.v1`, `sso_event.ldap_sync.success.v1`, `sso_event.saml_login.failure.v1`, `sso_event.saml_login.partial_failure.v1`, `sso_event.saml_login.skipped.v1`, `sso_event.saml_login.success.v1`, `sync_run.failure.v1`, `sync_run.partial_failure.v1`, `sync_run.skipped.v1`, `sync_run.success.v1`, `user_security_event.lockout.v1`
 * `filter` (object): Structured event payload filter.
 * `delivery_policy` (object): Event Subscription delivery policy.
 * `event_target_ids` (array(int64)): Event Target IDs this subscription sends to.

data/docs/file.md

@@ -3,6 +3,43 @@
 The Files::File object emulates a Ruby File object and can be used in
 may places where a Ruby File object can be used.
 
+## Downloads
+
+`download_file(local_path)`, `download_content(io)` and `read_io` stream a
+file's content without holding all of it in memory. When the SDK can tell that
+a download did not finish, it raises instead of returning part of the file:
+
+* A transfer the server refuses raises the `Net::HTTP` error for its status,
+  for example `Net::HTTPClientException` with the message `403 "Forbidden"`.
+  The error's response has no readable body, because the SDK stops before
+  reading it.
+* A body that stops short of its `Content-Length`, or a chunked body that
+  stops before its last chunk, raises `EOFError`. A lost connection raises its
+  own error, such as `Errno::ECONNRESET`.
+* An error writing to the IO given to `download_content` is raised unchanged.
+
+Two kinds of incomplete body cannot be detected. A body sent with neither a
+`Content-Length` nor chunked encoding ends when the connection closes, so it
+has no expected length. A gzip or deflate body that Net::HTTP decompresses has
+a `Content-Length` that counts compressed bytes, so a decompressed body framed
+only by `Content-Length` is not checked. Chunked bodies and ranges are checked
+whatever their encoding.
+
+When a download raises, whatever arrived before the failure has already been
+written: `download_file` can leave a partial file behind, and the IO given to
+`download_content` holds the partial content. `download_content` leaves that
+IO open, except that it closes the IO when the server refuses the transfer or
+writing to the IO fails.
+
+`read_io` returns a pipe that fills as the download proceeds. `read`, `gets`,
+`readline`, `readpartial`, `each_line`, `each` and `eof?` raise a download
+failure no later than they reach the end of the data. Other reads, such as
+`getbyte` or `IO.copy_stream`, see an ordinary end of file, so check the
+download by closing the pipe: `close` always releases it, and then raises a
+failure that no read has raised yet, unless another exception is already
+propagating. `Files::File#read`, `#gets`, `#readline`, `#readpartial` and
+`#each_line` read from `read_io` and raise the same way.
+
 ## Example File Object
 
 ```

data/docs/public_key.md

@@ -58,7 +58,7 @@ Files::PublicKey.list(
 * `cursor` (string): Used for pagination.  When a list request has more records available, cursors are provided in the response headers `X-Files-Cursor-Next` and `X-Files-Cursor-Prev`.  Send one of those cursor value here to resume an existing list from the next available record.  Note: many of our SDKs have iterator methods that will automatically handle cursor-based pagination.
 * `per_page` (int64): Number of records to show per page.  (Max: 10000, 1,000 or less is recommended).
 * `sort_by` (object): If set, sort records by the specified field in either `asc` or `desc` direction. Valid fields are `workspace_id`, `user_id`, `title` or `created_at`.
-* `filter` (object): If set, return records where the specified field is equal to the supplied value. Valid fields are `created_at` and `workspace_id`.
+* `filter` (object): If set, return records where the specified field is equal to the supplied value. Valid fields are `created_at` and `workspace_id`. Valid field combinations are `[ workspace_id, created_at ]`.
 * `filter_gt` (object): If set, return records where the specified field is greater than the supplied value. Valid fields are `created_at`.
 * `filter_gteq` (object): If set, return records where the specified field is greater than or equal the supplied value. Valid fields are `created_at`.
 * `filter_lt` (object): If set, return records where the specified field is less than the supplied value. Valid fields are `created_at`.

data/lib/files.com/api.rb

@@ -2,14 +2,15 @@
 
 module Files
   class Api
+    # A given block receives the response and can reject it by raising. The
+    # caller's options take on the resolved client and credentials only after
+    # the request, and that check, succeed.
     def self.send_request(path, verb, params, options)
       warn_on_options_in_params(params)
 
-      options[:client] ||= ApiClient.active_client
-
       headers = options.clone
       api_key = headers.delete(:api_key)
-      client = headers.delete(:client)
+      client = headers.delete(:client) || ApiClient.active_client
       session_id = headers.delete(:session_id)
       workspace_id = headers.delete(:workspace_id)
       if session = headers.delete(:session)
@@ -17,9 +18,13 @@ module Files
         session_id = session.id
       end
 
-      resp, options[:api_key], options[:session_id] = client.execute_request(
+      resp, api_key, session_id = client.execute_request(
         verb, path, api_key: api_key, headers: headers, params: params, session_id: session_id, workspace_id: workspace_id
       )
+      yield resp if block_given?
+      options[:client] = client
+      options[:api_key] = api_key
+      options[:session_id] = session_id
 
       # Hash#select returns an array before 1.9
       options_to_persist = {}

data/lib/files.com/api_client.rb

@@ -140,7 +140,7 @@ module Files
       begin
         resp = Response.from_faraday_response(http_resp)
       rescue JSON::ParserError
-        raise general_api_error(http_resp.status, http_resp.body)
+        raise unreadable_response_error(http_resp), cause: nil
       end
 
       @last_response = resp
@@ -164,22 +164,7 @@ module Files
 
     def stream_download(uri, io, range)
       if conn.adapter == Faraday::Adapter::NetHttp
-        uri = URI(uri)
-        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
-          request = Net::HTTP::Get.new uri
-          request["RANGE"] = "bytes=#{range[0]}-#{range[1]}" unless range.empty?
-          http.request request do |response|
-            io.fulfill_content_length(response.content_length) if io.respond_to?(:fulfill_content_length)
-            response.read_body do |chunk|
-              response.error! if response.code.to_i >= 300
-              io.ready! if io.respond_to?(:ready!)
-              io << chunk
-            rescue StandardError => e
-              io.do_set_error(e) if io.respond_to?(:do_set_error)
-              io.close
-            end
-          end
-        end
+        stream_download_with_net_http(URI(uri), io, range)
       else
         response = remote_request(:get, uri)
         io.fulfill_content_length(response.content_length) if io.respond_to?(:fulfill_content_length)
@@ -187,6 +172,85 @@ module Files
       end
     end
 
+    # Writes the body of a signed transfer URL to io as it arrives.
+    #
+    # Any failure while the response is open is raised only after Net::HTTP has
+    # let go of the connection. The Net::HTTP bundled with Ruby 3.0 retries a GET
+    # when an IOError or EOFError escapes the response block, which would write
+    # the body into io a second time.
+    private def stream_download_with_net_http(uri, io, range)
+      request = Net::HTTP::Get.new(uri)
+      request["Range"] = "bytes=#{range[0]}-#{range[1]}" unless range.empty?
+
+      failure = nil
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+        http.request(request) do |response|
+          write_download_body(response, io)
+        rescue StandardError => e
+          failure = e
+          break
+        end
+      end
+      raise failure if failure
+    end
+
+    private def write_download_body(response, io)
+      reject_unsuccessful_download(response, io)
+      io.fulfill_content_length(response.content_length) if io.respond_to?(:fulfill_content_length)
+
+      expected_bytes = expected_download_bytes(response)
+      received_bytes = 0
+      response.read_body do |chunk|
+        io.ready! if io.respond_to?(:ready!)
+        write_download_chunk(io, chunk)
+        received_bytes += chunk.bytesize
+      end
+      return if expected_bytes.nil? || received_bytes == expected_bytes
+
+      raise EOFError, "Transfer response ended after #{received_bytes} of #{expected_bytes} bytes"
+    end
+
+    # How many bytes read_body must yield, when the response says. Content-Length
+    # counts bytes on the wire, which read_body yields unchanged unless the body is
+    # chunked or Net::HTTP decompresses it. Net::HTTP quietly accepts a
+    # fixed-length body that stops short, and the version bundled with Ruby 3.0
+    # has no ignore_eof= to change that, so write_download_body counts the bytes.
+    private def expected_download_bytes(response)
+      response.content_length unless response.chunked? || decompressed_by_net_http?(response)
+    end
+
+    # Net::HTTP decompresses a gzip or deflate body as it reads it, but never a
+    # range. Ask before reading: decompressing removes the Content-Encoding.
+    private def decompressed_by_net_http?(response)
+      response.decode_content && !response.key?("content-range") &&
+      %w[gzip x-gzip deflate].include?(response["content-encoding"]&.downcase)
+    end
+
+    private def reject_unsuccessful_download(response, io)
+      response.error! unless response.is_a?(Net::HTTPSuccess)
+    rescue Net::HTTPExceptions => e
+      close_destination_after_failure(io, e)
+      raise
+    end
+
+    private def write_download_chunk(io, chunk)
+      io << chunk
+    rescue StandardError => e
+      close_destination_after_failure(io, e)
+      raise
+    end
+
+    # A refused transfer or a failing destination closes the destination, as it
+    # always has. Connection failures and short bodies leave it open so the caller
+    # can retry. Pipe readers learn why the download failed before the pipe
+    # closes, and a failure to close never replaces the download's own error.
+    private def close_destination_after_failure(io, failure)
+      io.do_set_error(failure) if io.respond_to?(:do_set_error)
+      io.close
+    rescue StandardError => e
+      Util.log_debug("Download destination close error", error_type: e.class, error_message: e.message)
+    end
+
     def cursor
       @last_response.http_headers["x-files-cursor"]
     end
@@ -245,8 +309,8 @@ module Files
 
         case e
         when Faraday::ClientError, Faraday::ServerError
-          if e.response and has_error_type?(e)
-            handle_error_response(e.response, error_context, is_transfer: is_transfer)
+          if (error_response = api_error_response(e.response))
+            handle_error_response(error_response, error_context, is_transfer: is_transfer)
           else
             handle_network_error(e, error_context, num_retries, base_url, is_transfer: is_transfer)
           end
@@ -260,8 +324,13 @@ module Files
       resp
     end
 
-    private def general_api_error(status, body)
-      APIError.new("Unexpected response object from API: #{body.inspect} (HTTP response code was #{status})", http_status: status, http_body: body)
+    # A successful response whose body is not JSON gave the SDK no usable
+    # answer. The body stays available as http_body but is left out of the
+    # message, and the parser error, which quotes it, is not kept as the cause.
+    private def unreadable_response_error(http_resp)
+      APIConnectionError.new("The Files.com API returned a response that is not valid JSON (HTTP response code was #{http_resp.status})",
+        http_status: http_resp.status, http_headers: http_resp.headers, http_body: http_resp.body
+      )
     end
 
     private def format_app_info(info)
@@ -271,21 +340,21 @@ module Files
       str
     end
 
-    private def handle_error_response(http_resp, context, is_transfer: false)
-      begin
-        resp = Response.from_faraday_hash(http_resp)
-        error_data = resp.data[:error] || resp.data[:errors]
-        error_data = error_data.first if error_data.is_a?(Array)
-        error_data = { message: error_data } if error_data.is_a?(String)
-
-        raise Error, "Unknown error" unless error_data
-      rescue JSON::ParserError, Error
-        raise APIError.new("Transfer request failed", http_status: http_resp[:status]), cause: nil if is_transfer
-
-        raise general_api_error(http_resp[:status], http_resp[:body])
-      end
+    # A failed response carrying a Files.com error object: a JSON object with an
+    # error message or type. Any other body, JSON or not, is not an answer the
+    # SDK can use.
+    private def api_error_response(http_resp)
+      return unless http_resp
+
+      resp = Response.from_faraday_hash(http_resp)
+      error_object = resp.data
+      resp if error_object.is_a?(Hash) && (error_object[:error] || error_object[:errors] || error_object[:type])
+    rescue JSON::ParserError
+      nil
+    end
 
-      error = specific_api_error(resp, error_data, context, is_transfer: is_transfer)
+    private def handle_error_response(resp, context, is_transfer: false)
+      error = specific_api_error(resp, context, is_transfer: is_transfer)
 
       error.response = resp
       raise error, cause: nil if is_transfer
@@ -293,30 +362,93 @@ module Files
       raise error
     end
 
-    private def specific_api_error(resp, error_data, _context, is_transfer: false)
-      message = is_transfer ? "Transfer request failed" : error_data[:message]
+    private def specific_api_error(resp, _context, is_transfer: false)
+      error_data = error_details(resp.data)
+      message = if is_transfer
+                  "Transfer request failed"
+                elsif error_data[:message].is_a?(String)
+                  without_url_credentials(error_data[:message])
+                else
+                  "The Files.com API returned an error without a message (HTTP response code was #{resp.http_status})"
+                end
       Util.log_error("API error", status: resp.http_status, error_message: message)
 
-      opts = {
+      api_error_class(resp.data[:type]).new(message,
         http_body: resp.http_body,
         http_headers: resp.http_headers,
         http_status: resp.http_status,
         json_body: resp.data,
-        code: error_data[:code] || resp.http_status,
-      }
-
-      return APIError.new(message, **opts) unless resp&.data&.dig(:type)
+        code: error_data[:code] || resp.http_status
+      )
+    end
 
-      begin
-        error_type = resp.data[:type].split("/").last
-        error_class_name = "#{error_type.split("-").map(&:capitalize).join}Error"
-        error_class = Files.const_get(error_class_name)
-        error_class.new(message, **opts)
-      rescue NameError
-        APIError.new(message, **opts)
+    # Where a scheme-qualified URL starts. A scheme begins at the first letter of
+    # a run of scheme characters, and only a run's first character can start
+    # one, so each run is read a bounded number of times however long it is.
+    URL_START = /(?<![a-z0-9+.-])[0-9+.-]*+[a-z][a-z0-9+.-]*+:\/\//i
+    private_constant :URL_START
+
+    # A URL in server text, with the apostrophe that opens it if it is quoted.
+    # Before its query or fragment, a URL ends at whitespace, a character that
+    # cannot appear in a URL, or where the next URL starts, so each URL in a
+    # list is redacted on its own. Apostrophes can appear in a URL, so they stay
+    # part of it. A query or fragment runs to the end of the text around it.
+    URL_IN_TEXT = /(?<opening>'?)(?<url>#{URL_START}(?:(?!'?#{URL_START})[^\s"<>?#])*+(?:[?#][^\s"<>]*)?)/i
+    private_constant :URL_IN_TEXT
+
+    # Server text can quote a URL whose user info, query or fragment is a
+    # credential, such as a signed transfer URL. Error messages and logs below
+    # DEBUG keep where the URL points and drop those parts; the raw response
+    # fields keep them.
+    private def without_url_credentials(text)
+      text.gsub(URL_IN_TEXT) do
+        opening, url = Regexp.last_match.captures
+        closing = opening.empty? ? "" : closing_quote(url)
+        "#{opening}#{without_credentials(url.delete_suffix(closing))}#{closing}"
       end
     end
 
+    # The apostrophe that closes a URL quoted with apostrophes, with any
+    # punctuation after it, or "" when the URL does not end that way.
+    private def closing_quote(url)
+      quote = url.rindex("'")
+      quote && url[quote..].match?(/\A'[.,;:!?)]*\z/) ? url[quote..] : ""
+    end
+
+    # The authority, which may be empty, ends at the first "/", "?" or "#";
+    # only an "@" inside it marks user info.
+    private def without_credentials(url)
+      scheme, _, rest = url.partition("://")
+      authority, separator, path = rest.partition(/[\/?#]/)
+      authority = "[redacted]@#{authority.rpartition('@').last}" if authority.include?("@")
+      path = "#{separator}#{path}"
+      credentials_at = path.index(/[?#]/)
+      path = "#{path[0...credentials_at]}?[redacted]" if credentials_at
+      "#{scheme}://#{authority}#{path}"
+    end
+
+    # The message and code in an error object's "error" or "errors" field, which
+    # holds a message, an object with a message and code, or a list of either.
+    private def error_details(error_object)
+      details = error_object[:error] || error_object[:errors]
+      details = details.first if details.is_a?(Array)
+      details = { message: details } if details.is_a?(String)
+      details.is_a?(Hash) ? details : {}
+    end
+
+    # The APIError subclass an error type names, such as NotFoundError for
+    # "not-found" or LockoutRegionMismatchError for
+    # "not-authenticated/lockout-region-mismatch". Any other type is an APIError.
+    private def api_error_class(type)
+      return APIError unless type.is_a?(String)
+
+      name = type.split("/").last.to_s.split("-").map(&:capitalize).join
+      error_class = Files.const_get("#{name}Error", false)
+      error_class.is_a?(Class) && error_class < APIError ? error_class : APIError
+    rescue NameError
+      APIError
+    end
+
     private def handle_network_error(error, _context, num_retries, base_url = nil, is_transfer: false)
       base_url ||= Files.base_url
 
@@ -371,12 +503,6 @@ module Files
       headers
     end
 
-    private def has_error_type?(e)
-      Response.from_faraday_hash(e.response).data&.dig(:type) ? true : false
-    rescue JSON::ParserError, Error
-      false
-    end
-
     private def log_request(context, num_retries, no_body: false)
       Util.log_info("Request", method: context.method, num_retries: num_retries, path: context.path)
       Util.log_debug("Request details", body: context.body, query_params: context.query_params) unless no_body