yandex360 3.2.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3847fa893972117ef8e0fd58434e72681dbed2fe78c58ede460fc0efa54975f
-  data.tar.gz: 92d87a5dad06e62980a020dd89b587ff93455647faee382f627d047bb5cf444d
+  metadata.gz: 9c0a4afac73e5265e480369e774ae31ef8e2e1e647b7443fb73c9eb54a961835
+  data.tar.gz: 0f931993c435fc14e439f838122db029e80e2804ac442e5e1b19f3610581f341
 SHA512:
-  metadata.gz: 552e40670b3e7c49de3edeea31e047a4065f75c447f4d348779a7839a51631b16bcfe33d6c90fec7b22b82bf1dd11e3cb7c021d3b26f8c18efe9f00c4136c7eb
-  data.tar.gz: 98194f3ecb959075d2b5c985294623332204cb392f7bc5702ca1977e40fe0f851048f88efa63305fed1a7504978ef008c70abd044054150b0d1e60abe8306d3f
+  metadata.gz: 90967ccab57a20f2aa22f4e1e5fcad39f073a024b44c61ba509dfdba8d04dbd1b065fb62291e4f6796d58172a988a2de6b88abe2fe9e36ffb0333a11be2b4740
+  data.tar.gz: 9f86f9c0edfae65a807cdf08c11a58c5bb3bb71200ce705a7a9f76ee050b1d5244f0df38334ab10700a6146dd51b3ef7fe8fa87358788d5f037f034b5105cc6c

data/CHANGELOG.md

@@ -6,6 +6,114 @@ follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [4.0.0] - 2026-09-21
+
+Every path in the gem has now been read against the published reference
+individually. Five areas were wrong, and the four services that follow were
+calling endpoints that do not exist.
+
+### Breaking
+
+- `two_fa` covers the organization only, and its methods have changed. Three of
+  the five called paths that are not in the API:
+  `/security/v1/org/{orgId}/users/{userId}/2fa/enable`, `/disable` and
+  `/status` do not exist. A fourth, `configure_domain`, used the right path but
+  sent `enabled`, which the endpoint does not accept.
+
+  `Domain2FAService` puts all three operations on one path and distinguishes
+  them by verb:
+
+  | Operation | Method |
+  |---|---|
+  | `two_fa.status(org_id:)` | `GET /security/v1/org/{orgId}/domain_2fa` |
+  | `two_fa.enable(org_id:, duration:, ...)` | `POST` to the same path |
+  | `two_fa.disable(org_id:)` | `DELETE` to the same path |
+
+  `duration` is required, since the API does not default it, and
+  `logout_users` and `validation_method` are optional. `domain_status` remains
+  as an alias of `status` that warns, removed in 5.0. `configure_domain` is
+  gone: with enabling and disabling now separate verbs there is nothing for it
+  to mean.
+
+  Per-employee 2FA was never here. Reading it is `users.get2FA` and clearing
+  the phone is `users.delete_2fa_phone`, both of which were already correct.
+
+- `client.post_settings` is now `client.mail_settings`, and every method on it
+  has changed. The old resource called paths that are not part of the API:
+  `/directory/v1/org/{orgId}/users/{userId}/settings/mail` and its forwarding
+  sub-paths do not exist, so none of it could have worked. The real service is
+  `MailUserSettingsService`, under
+  `/admin/v1/org/{orgId}/mail/users/{userId}/settings`, and it covers three
+  settings rather than one:
+
+  | Setting | Path | Methods |
+  |---|---|---|
+  | Contact collection | `address_book` | `address_book`, `update_address_book` |
+  | Sender name and signatures | `sender_info` | `sender_info`, `update_sender_info` |
+  | Auto-replies and forwards | `user_rules` | `rules`, `create_rule`, `delete_rule` |
+
+  Forwarding is one of two kinds of rule rather than a thing of its own, so
+  `forwarding_list`, `add_forwarding` and `delete_forwarding` have no
+  successors of the same shape. `client.post_settings` stays as an accessor
+  that warns and returns the new resource, removed in 5.0.
+
+- `domains.verify` and `domains.info` are gone. `DomainService` has seven
+  operations and neither is among them: there is no way to verify a domain
+  through a dedicated call, and no way to read one domain. What verification
+  actually needs is `domains.connection_status`, which answers the confirmation
+  methods and their codes. `domains.find` replaces `info` by walking the list,
+  and is named for what it does, since it costs a request per page.
+- `organizations.info` now searches the list rather than fetching.
+  `OrganizationsService` offers only a list, so the path it used,
+  `/directory/v1/org/{orgId}`, does not exist. The method keeps its name and
+  its arguments and returns nil when the token does not reach that
+  organization.
+
+### Added
+
+- The four domain operations the gem never had: `connection_status`,
+  `dkim_status`, `enable_dkim` and `disable_dkim`.
+
+- Pagination on the three lists that have it and were missing it: `domains` and
+  `dns` take `page` and `per_page`, and `organizations` pages by token, so it
+  takes `page_size` and no `page`. Which list paginates and how was read from
+  the reference one endpoint at a time rather than assumed, and the lists that
+  answer everything at once, group members, mailbox access rights and service
+  applications, are left without arguments the API would ignore. Both READMEs
+  now say which is which.
+- `groups.members`, answering the departments, groups and employees a group
+  holds. `ListMembers` returns all three and `groups.users` shows one, so
+  members of the other two kinds were invisible.
+
+### Fixed
+
+- `users.add_alias` returns a `User` again. `CreateUserAlias` answers the whole
+  employee, aliases included, not the alias. It was changed to `Alias` in 3.0.0
+  on the strength of a stub that had invented that shape, which is exactly the
+  mistake the typed records were meant to expose rather than commit.
+- `departments.add_alias` returns a `Department` for the same reason, and
+  `departments.delete_alias` a `DepartmentAlias`, since deleting one does
+  answer `{alias, removed}`.
+- The stub for `groups.delete_user` said `removed`; `DeleteMember` answers
+  `deleted`. `GroupService_Delete` does answer `removed`, so the two really do
+  differ and the spec now asserts each correctly.
+
+### Internal
+
+- The Trivy scan is removed. It duplicated `bundle audit`: across 86 runs it
+  reported the same five advisories in faraday and json, and dropped to zero
+  the day the lockfile was refreshed. It never found anything `bundle audit`
+  did not, there is no Dockerfile or infrastructure here for it to scan, and
+  its findings went to the Security tab where they sat unread for months while
+  the failing `bundle audit` step is what actually forced the fix. It was also
+  the job that broke, failing to download its own binary. CodeQL remains the
+  primary analysis, alongside bundle audit, dependency review and Dependabot.
+
+### Notes
+
+Every path and response shape in the gem has now been checked against the
+published reference rather than against our own stubs.
+
 ## [3.2.0] - 2026-09-21
 
 ### Added
@@ -331,7 +439,8 @@ and is kept below unchanged. Release notes for those versions are also on the
 - build(deps): bump ruby/setup-ruby from 1.316.0 to 1.319.0 by @dependabot[bot] in #149
 - build(deps): bump github/codeql-action from 4 to 4.37.4 by @dependabot[bot] in #152
 
-[Unreleased]: https://github.com/ruby-api-client/yandex360/compare/v3.2.0...HEAD
+[Unreleased]: https://github.com/ruby-api-client/yandex360/compare/v4.0.0...HEAD
+[4.0.0]: https://github.com/ruby-api-client/yandex360/compare/v3.2.0...v4.0.0
 [3.2.0]: https://github.com/ruby-api-client/yandex360/compare/v3.1.0...v3.2.0
 [3.1.0]: https://github.com/ruby-api-client/yandex360/compare/v3.0.0...v3.1.0
 [3.0.0]: https://github.com/ruby-api-client/yandex360/compare/v2.0.0...v3.0.0

data/README.md

@@ -27,7 +27,7 @@ A comprehensive Ruby wrapper for the [Yandex 360 API](https://yandex.ru/dev/api3
 - [Resources](#resources)
   - **Directory**: [Organizations](#organizations), [Users](#users), [Departments](#departments), [Groups](#groups), [External Contacts](#external-contacts)
   - **Domains**: [Domains](#domains), [DNS Records](#dns-records)
-  - **Mail**: [Post Settings](#post-settings), [Mailboxes](#mailboxes), [Mail Routing](#mail-routing), [Domain Policies](#domain-policies), [Antispam](#antispam)
+  - **Mail**: [Mail Settings](#mail-settings), [Mailboxes](#mailboxes), [Mail Routing](#mail-routing), [Domain Policies](#domain-policies), [Antispam](#antispam)
   - **Security**: [Two-Factor Authentication (2FA)](#two-factor-authentication-2fa), [User Sessions](#user-sessions), [Password Policy](#password-policy), [Audit Logs](#audit-logs), [Service Applications](#service-applications)
 - [API Reference](#api-reference)
 - [Development](#development)
@@ -58,7 +58,7 @@ A comprehensive Ruby wrapper for the [Yandex 360 API](https://yandex.ru/dev/api3
 Add this line to your application's `Gemfile`:
 
 ```ruby
-gem 'yandex360', '~> 3.0'
+gem 'yandex360', '~> 4.0'
 ```
 
 Then execute:
@@ -85,6 +85,11 @@ For more information, visit the [Yandex 360 API Documentation](https://yandex.ru
 
 ## Upgrading from 1.x
 
+Coming from 3.x instead? The breaking changes in 4.0 are listed in the
+[changelog](CHANGELOG.md): four resources were calling endpoints that do not
+exist and have been corrected.
+
+
 Two major versions happened at once: 1.1.4 was the last published release
 before 3.0.0. Everything that needs your attention is here. The
 [changelog](CHANGELOG.md) has the reasoning.
@@ -388,9 +393,15 @@ users.auto_paginate.each {|user| puts user.nickname }
 first_fifty = client.users.list(org_id: 1234567, per_page: 25).auto_paginate.first(50)
 ```
 
-Both are available on `users`, `groups`, `departments`, `external_contacts`
-and the two mailbox lists. Arguments given to the original call, such as
-`per_page` or a department's `parent_id`, are carried into the following pages.
+Not every list paginates, and those that do differ. `users`, `groups`,
+`departments`, `external_contacts`, `domains`, `dns` and the two mailbox
+listings take `page` and `per_page`. `organizations` and the two audit logs
+page by token instead, so they take `page_size` and no `page`. Group members,
+mailbox access rights and service applications answer everything at once and
+take neither.
+
+Arguments given to the original call, such as `per_page` or a department's
+`parent_id`, are carried into the following pages.
 
 ## Response Objects
 
@@ -538,7 +549,7 @@ covered.
 |  | `client.external_contacts` | [External Contacts](#external-contacts) |
 | Domains | `client.domains` | [Domains](#domains) |
 |  | `client.dns` | [DNS Records](#dns-records) |
-| Mail | `client.post_settings` | [Post Settings](#post-settings) |
+| Mail | `client.mail_settings` | [Mail Settings](#mail-settings) |
 |  | `client.mailboxes` | [Mailboxes](#mailboxes) |
 |  | `client.routing` | [Mail Routing](#mail-routing) |
 |  | `client.domain_policies` | [Domain Policies](#domain-policies) |
@@ -571,6 +582,10 @@ puts "Email: #{org.email}"
 puts "Subscription plan: #{org.subscription_plan}"
 ```
 
+The service offers a list and nothing narrower, so this searches it rather than
+fetching one organization. A token usually reaches a single organization, so it
+is one request in practice.
+
 ---
 
 ### Users
@@ -900,53 +915,44 @@ client.external_contacts.delete(org_id: 1234567, contact_id: created.id)
 
 ### Domains
 
-Manage organization domains and verify ownership.
-
-#### List domains
-
 ```ruby
-domains = client.domains.list(org_id: 1234567)
-domains.each do |domain|
-  puts "Domain: #{domain.name}"
-  puts "Status: #{domain.status}"
-  puts "Verified: #{domain.verified}"
-end
-```
+domains = client.domains.list(org_id: 1234567, page: 1, per_page: 10)
+domains.each {|domain| puts "#{domain.name} verified=#{domain.verified}" }
 
-#### Add a domain
-
-```ruby
-domain = client.domains.add(
-  org_id: 1234567,
-  name: "example.com"
-)
-puts "Added domain: #{domain.name}"
-puts "Verification status: #{domain.status}"
+client.domains.add(org_id: 1234567, name: "example.com")
+client.domains.delete(org_id: 1234567, domain: "example.com")
 ```
 
-#### Get domain information
+There is no endpoint for reading one domain, so `find` walks the list. It
+costs a request per page rather than one, which is why it is named for what it
+does:
 
 ```ruby
-domain = client.domains.info(org_id: 1234567, domain: "example.com")
-puts "Domain: #{domain.name}"
-puts "Status: #{domain.status}"
-puts "Verified: #{domain.verified}"
-puts "Master admin email: #{domain.master_admin}"
+client.domains.find(org_id: 1234567, domain: "example.com")
 ```
 
-#### Verify domain ownership
+Connection status carries the confirmation methods and their codes, which is
+what verifying a domain needs:
 
 ```ruby
-domain = client.domains.verify(org_id: 1234567, domain: "example.com")
-puts "Verification status: #{domain.status}"
+status = client.domains.connection_status(org_id: 1234567, domain: "example.com")
+status.status
+status.methods.each {|method| puts "#{method.method}: #{method.code}" }
 ```
 
-#### Delete a domain
+The DKIM signature:
 
 ```ruby
-client.domains.delete(org_id: 1234567, domain: "example.com")
+dkim = client.domains.dkim_status(org_id: 1234567, domain: "example.com")
+dkim.enabled
+dkim.public_key
+
+client.domains.enable_dkim(org_id: 1234567, domain: "example.com")
+client.domains.disable_dkim(org_id: 1234567, domain: "example.com")
 ```
 
+Cyrillic domains must be given in Punycode, as the API documents.
+
 ---
 
 ### DNS Records
@@ -1022,55 +1028,53 @@ client.dns.delete(
 
 ---
 
-### Post Settings
-
-Manage email settings for users including forwarding rules.
+### Mail Settings
 
-#### Get user mail settings
+Per-employee settings: automatic contact collection, the sender name and
+signatures, and the auto-reply and forwarding rules.
 
 ```ruby
-settings = client.post_settings.list(org_id: 1234567, user_id: 987654321)
-puts "Signature: #{settings.signature}"
-puts "Reply-to: #{settings.reply_to}"
-```
+# Automatic contact collection
+book = client.mail_settings.address_book(org_id: 1234567, user_id: 987654321)
+book.collect_addresses
 
-#### Update mail settings
+client.mail_settings.update_address_book(
+  org_id: 1234567, user_id: 987654321, collect_addresses: false
+)
 
-```ruby
-updated = client.post_settings.update(
+# Sender name, default address and signatures
+info = client.mail_settings.sender_info(org_id: 1234567, user_id: 987654321)
+puts "#{info.from_name} <#{info.default_from}>"
+info.signs.each {|sign| puts sign.text }
+
+client.mail_settings.update_sender_info(
   org_id: 1234567,
   user_id: 987654321,
-  signature: "Best regards,\nJohn Doe",
-  replyTo: "john.doe@example.com"
+  from_name: "Ivan Ivanov",
+  sign_position: "under" # or "bottom", the default
 )
 ```
 
-#### Manage email forwarding
+Auto-replies and forwards are two kinds of the same rule and arrive together:
 
 ```ruby
-# List forwarding addresses
-forwardings = client.post_settings.forwarding_list(
-  org_id: 1234567,
-  user_id: 987654321
-)
+rules = client.mail_settings.rules(org_id: 1234567, user_id: 987654321)
+rules.autoreplies
+rules.forwards
 
-forwardings.each do |forwarding|
-  puts "Forwarding to: #{forwarding.address}"
-end
-
-# Add forwarding address
-client.post_settings.add_forwarding(
-  org_id: 1234567,
-  user_id: 987654321,
-  address: "forward@example.com"
+# One rule per call, of one kind. An auto-reply:
+created = client.mail_settings.create_rule(
+  org_id: 1234567, user_id: 987654321,
+  rule_name: "On holiday", text: "Back on Monday"
 )
 
-# Delete forwarding address
-client.post_settings.delete_forwarding(
-  org_id: 1234567,
-  user_id: 987654321,
-  address: "forward@example.com"
+# Or a forward:
+client.mail_settings.create_rule(
+  org_id: 1234567, user_id: 987654321,
+  rule_name: "To archive", address: "archive@example.com", with_store: true
 )
+
+client.mail_settings.delete_rule(org_id: 1234567, user_id: 987654321, rule_id: created.rule_id)
 ```
 
 ---
@@ -1219,51 +1223,33 @@ puts "Allowlist cleared"
 
 ### Two-Factor Authentication (2FA)
 
-Manage two-factor authentication settings for users and the entire domain.
-
-#### Enable 2FA for a user
-
-```ruby
-result = client.two_fa.enable(org_id: 1234567, user_id: 987654321)
-puts "2FA enabled successfully"
-```
-
-#### Disable 2FA for a user
-
-```ruby
-result = client.two_fa.disable(org_id: 1234567, user_id: 987654321)
-puts "2FA disabled successfully"
-```
-
-#### Check user 2FA status
+Mandatory 2FA for the whole organization. All three calls share one path and
+differ only by verb, which is why there is no separate enable or disable
+endpoint.
 
 ```ruby
-status = client.two_fa.status(org_id: 1234567, user_id: 987654321)
-puts "2FA enabled: #{status.enabled}"
-puts "Has TOTP: #{status.has_totp}"
-```
+settings = client.two_fa.status(org_id: 1234567)
+settings.enabled
+settings.duration    # seconds an employee may postpone setting it up
+settings.enabled_at
 
-#### Get domain-wide 2FA status
+# duration is required: the API does not default it.
+client.two_fa.enable(
+  org_id: 1234567,
+  duration: 3600,
+  logout_users: true,        # optional, ends every session
+  validation_method: "phone" # optional, "default" or "phone"
+)
 
-```ruby
-domain_status = client.two_fa.domain_status(org_id: 1234567)
-puts "Domain 2FA enabled: #{domain_status.enabled}"
+client.two_fa.disable(org_id: 1234567)
 ```
 
-#### Configure domain-wide 2FA
+Per-employee 2FA is not here. It belongs to the employee, so it lives on
+`users`:
 
 ```ruby
-# Enable 2FA for entire domain
-result = client.two_fa.configure_domain(
-  org_id: 1234567,
-  enabled: true
-)
-
-# Disable 2FA for entire domain
-result = client.two_fa.configure_domain(
-  org_id: 1234567,
-  enabled: false
-)
+client.users.get2FA(org_id: 1234567, user_id: 987654321)
+client.users.delete_2fa_phone(org_id: 1234567, user_id: 987654321)
 ```
 
 ---
@@ -1381,7 +1367,7 @@ date. See the sections above for what each one does.
 
 ```ruby
 # Directory
-organizations.list
+organizations.list(page_size: 10, page_token: nil)
 organizations.info(org_id:)
 users.add(org_id:, dep_id:, **user_params)
 users.add_alias(org_id:, user_id:, user_alias:)
@@ -1409,6 +1395,7 @@ groups.info(org_id:, group_id:)
 groups.params(org_id:, group_id:)   # deprecated, use info
 groups.list(org_id:, page: 1, per_page: 10)
 groups.users(org_id:, group_id:)
+groups.members(org_id:, group_id:)
 groups.create(org_id:, name:, **group_params)
 groups.delete(org_id:, group_id:)
 groups.delete_user(org_id:, group_id:, type:, user_id:)
@@ -1421,22 +1408,27 @@ external_contacts.update_emails(org_id:, contact_id:, emails:)
 external_contacts.update_phones(org_id:, contact_id:, phones:)
 
 # Domains
-domains.list(org_id:)
+domains.list(org_id:, page: 1, per_page: 10)
+domains.find(org_id:, domain:)
 domains.add(org_id:, name:, **params)
-domains.info(org_id:, domain:)
 domains.delete(org_id:, domain:)
-domains.verify(org_id:, domain:)
-dns.list(org_id:, domain:)
+domains.connection_status(org_id:, domain:)
+domains.dkim_status(org_id:, domain:)
+domains.enable_dkim(org_id:, domain:)
+domains.disable_dkim(org_id:, domain:)
+dns.list(org_id:, domain:, page: 1, per_page: 50)
 dns.create(org_id:, domain:, **params)
 dns.update(org_id:, domain:, record_id:, **params)
 dns.delete(org_id:, domain:, record_id:)
 
 # Mail
-post_settings.list(org_id:, user_id:)
-post_settings.update(org_id:, user_id:, **params)
-post_settings.forwarding_list(org_id:, user_id:)
-post_settings.add_forwarding(org_id:, user_id:, address:)
-post_settings.delete_forwarding(org_id:, user_id:, address:)
+mail_settings.address_book(org_id:, user_id:)
+mail_settings.update_address_book(org_id:, user_id:, collect_addresses:)
+mail_settings.sender_info(org_id:, user_id:)
+mail_settings.update_sender_info(org_id:, user_id:, **params)
+mail_settings.rules(org_id:, user_id:)
+mail_settings.create_rule(org_id:, user_id:, **params)
+mail_settings.delete_rule(org_id:, user_id:, rule_id:)
 mailboxes.shared_list(org_id:, page: 1, per_page: 10)
 mailboxes.create_shared(org_id:, email:, name:, description:)
 mailboxes.shared_info(org_id:, resource_id:)
@@ -1458,11 +1450,10 @@ antispam.create(org_id, *strings)
 antispam.delete(org_id:)
 
 # Security
-two_fa.enable(org_id:, user_id:)
-two_fa.disable(org_id:, user_id:)
-two_fa.status(org_id:, user_id:)
+two_fa.status(org_id:)
+two_fa.enable(org_id:, duration:, logout_users: nil, validation_method: nil)
+two_fa.disable(org_id:)
 two_fa.domain_status(org_id:)
-two_fa.configure_domain(org_id:, enabled:)
 sessions.info(org_id:)
 sessions.update(org_id:, auth_ttl:)
 sessions.logout(org_id:, user_id:)