octoprint 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +10 -0
  3. data/LICENSE.txt +21 -0
  4. data/README.md +336 -0
  5. data/lib/octoprint/access/group.rb +88 -0
  6. data/lib/octoprint/access/groups.rb +166 -0
  7. data/lib/octoprint/access/login_response.rb +63 -0
  8. data/lib/octoprint/access/permission.rb +71 -0
  9. data/lib/octoprint/access/permissions.rb +29 -0
  10. data/lib/octoprint/access/user.rb +95 -0
  11. data/lib/octoprint/access/users.rb +347 -0
  12. data/lib/octoprint/auto_initializable.rb +219 -0
  13. data/lib/octoprint/base_resource.rb +139 -0
  14. data/lib/octoprint/client.rb +151 -0
  15. data/lib/octoprint/connection/options.rb +44 -0
  16. data/lib/octoprint/connection/settings.rb +35 -0
  17. data/lib/octoprint/connection.rb +74 -0
  18. data/lib/octoprint/deserializable.rb +483 -0
  19. data/lib/octoprint/exceptions.rb +30 -0
  20. data/lib/octoprint/files/file.rb +55 -0
  21. data/lib/octoprint/files/folder.rb +29 -0
  22. data/lib/octoprint/files/operation_result.rb +37 -0
  23. data/lib/octoprint/files/refs.rb +19 -0
  24. data/lib/octoprint/files.rb +238 -0
  25. data/lib/octoprint/job/information.rb +42 -0
  26. data/lib/octoprint/job/progress.rb +46 -0
  27. data/lib/octoprint/job.rb +140 -0
  28. data/lib/octoprint/languages/language_pack.rb +31 -0
  29. data/lib/octoprint/languages.rb +102 -0
  30. data/lib/octoprint/location.rb +23 -0
  31. data/lib/octoprint/logs/log_file.rb +59 -0
  32. data/lib/octoprint/logs/references.rb +28 -0
  33. data/lib/octoprint/logs.rb +98 -0
  34. data/lib/octoprint/printer/bed.rb +32 -0
  35. data/lib/octoprint/printer/chamber.rb +29 -0
  36. data/lib/octoprint/printer/command.rb +129 -0
  37. data/lib/octoprint/printer/custom_control/input.rb +45 -0
  38. data/lib/octoprint/printer/custom_control.rb +119 -0
  39. data/lib/octoprint/printer/error_information.rb +104 -0
  40. data/lib/octoprint/printer/heater.rb +113 -0
  41. data/lib/octoprint/printer/history_query.rb +25 -0
  42. data/lib/octoprint/printer/printhead.rb +105 -0
  43. data/lib/octoprint/printer/sd.rb +97 -0
  44. data/lib/octoprint/printer/state.rb +41 -0
  45. data/lib/octoprint/printer/state_flags.rb +70 -0
  46. data/lib/octoprint/printer/temperature_attributes.rb +70 -0
  47. data/lib/octoprint/printer/temperature_data.rb +53 -0
  48. data/lib/octoprint/printer/temperature_data_point.rb +73 -0
  49. data/lib/octoprint/printer/temperature_reading.rb +47 -0
  50. data/lib/octoprint/printer/temperature_state.rb +67 -0
  51. data/lib/octoprint/printer/tool.rb +154 -0
  52. data/lib/octoprint/printer.rb +126 -0
  53. data/lib/octoprint/printer_profiles/printer_profile.rb +40 -0
  54. data/lib/octoprint/printer_profiles.rb +158 -0
  55. data/lib/octoprint/server_information.rb +51 -0
  56. data/lib/octoprint/server_version.rb +52 -0
  57. data/lib/octoprint/settings/webcam.rb +135 -0
  58. data/lib/octoprint/settings.rb +133 -0
  59. data/lib/octoprint/slicing/profile.rb +65 -0
  60. data/lib/octoprint/slicing/slicer.rb +83 -0
  61. data/lib/octoprint/slicing.rb +227 -0
  62. data/lib/octoprint/system_commands/command.rb +41 -0
  63. data/lib/octoprint/system_commands.rb +110 -0
  64. data/lib/octoprint/timelapse/config.rb +68 -0
  65. data/lib/octoprint/timelapse/file_attributes.rb +50 -0
  66. data/lib/octoprint/timelapse/rendered.rb +51 -0
  67. data/lib/octoprint/timelapse/unrendered.rb +43 -0
  68. data/lib/octoprint/timelapse.rb +221 -0
  69. data/lib/octoprint/types.rb +140 -0
  70. data/lib/octoprint/util.rb +151 -0
  71. data/lib/octoprint/version.rb +7 -0
  72. data/lib/octoprint/wizard.rb +57 -0
  73. data/lib/octoprint.rb +57 -0
  74. data/rbi/octoprint/access/group.rbi +46 -0
  75. data/rbi/octoprint/access/login_response.rbi +22 -0
  76. data/rbi/octoprint/access/permission.rbi +34 -0
  77. data/rbi/octoprint/access/user.rbi +43 -0
  78. data/rbi/octoprint/connection/options.rbi +28 -0
  79. data/rbi/octoprint/connection/settings.rbi +19 -0
  80. data/rbi/octoprint/connection.rbi +13 -0
  81. data/rbi/octoprint/files/file.rbi +61 -0
  82. data/rbi/octoprint/files/folder.rbi +22 -0
  83. data/rbi/octoprint/files/operation_result.rbi +22 -0
  84. data/rbi/octoprint/files/refs.rbi +16 -0
  85. data/rbi/octoprint/job/information.rbi +22 -0
  86. data/rbi/octoprint/job/progress.rbi +25 -0
  87. data/rbi/octoprint/job.rbi +22 -0
  88. data/rbi/octoprint/languages/language_pack.rbi +19 -0
  89. data/rbi/octoprint/languages.rbi +13 -0
  90. data/rbi/octoprint/logs/log_file.rbi +19 -0
  91. data/rbi/octoprint/logs/references.rbi +13 -0
  92. data/rbi/octoprint/logs.rbi +13 -0
  93. data/rbi/octoprint/printer/bed.rbi +22 -0
  94. data/rbi/octoprint/printer/chamber.rbi +22 -0
  95. data/rbi/octoprint/printer/custom_control/input.rbi +22 -0
  96. data/rbi/octoprint/printer/custom_control.rbi +67 -0
  97. data/rbi/octoprint/printer/error_information.rbi +25 -0
  98. data/rbi/octoprint/printer/sd.rbi +13 -0
  99. data/rbi/octoprint/printer/state.rbi +19 -0
  100. data/rbi/octoprint/printer/state_flags.rbi +43 -0
  101. data/rbi/octoprint/printer/temperature_data.rbi +19 -0
  102. data/rbi/octoprint/printer/temperature_data_point.rbi +22 -0
  103. data/rbi/octoprint/printer/temperature_reading.rbi +19 -0
  104. data/rbi/octoprint/printer/temperature_state.rbi +22 -0
  105. data/rbi/octoprint/printer/tool.rbi +22 -0
  106. data/rbi/octoprint/printer.rbi +19 -0
  107. data/rbi/octoprint/printer_profiles/printer_profile.rbi +46 -0
  108. data/rbi/octoprint/printer_profiles.rbi +13 -0
  109. data/rbi/octoprint/server_information.rbi +16 -0
  110. data/rbi/octoprint/server_version.rbi +19 -0
  111. data/rbi/octoprint/settings/webcam.rbi +34 -0
  112. data/rbi/octoprint/slicing/profile.rbi +28 -0
  113. data/rbi/octoprint/slicing/slicer.rbi +31 -0
  114. data/rbi/octoprint/system_commands/command.rbi +25 -0
  115. data/rbi/octoprint/system_commands.rbi +16 -0
  116. data/rbi/octoprint/timelapse/config.rbi +31 -0
  117. data/rbi/octoprint/timelapse/rendered.rbi +31 -0
  118. data/rbi/octoprint/timelapse/unrendered.rbi +34 -0
  119. data/rbi/octoprint/timelapse.rbi +22 -0
  120. data/rbi/octoprint/util.rbi +19 -0
  121. data/rbi/octoprint.rbi +1848 -0
  122. metadata +264 -0
@@ -0,0 +1,63 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ module Octoprint
5
+ module Access
6
+ # The response of a login request (`POST /api/login`)
7
+ #
8
+ # OctoPrint returns a user record with a few extra fields. The user record is
9
+ # wrapped in a {User} (see {#user}), and the extra fields have their own readers.
10
+ #
11
+ # @example Get a session key for the push API
12
+ # login = Octoprint::Access::Users.login
13
+ # login.user.name # => "sophie"
14
+ # login.session # => "5f8c1a..."
15
+ # login.is_external_client # => false
16
+ # login.login_mechanism # => "apikey"
17
+ #
18
+ # @see https://docs.octoprint.org/en/1.11.8/api/general.html#data-model
19
+ class LoginResponse
20
+ include AutoInitializable
21
+ include Deserializable
22
+
23
+ # Fields of the login response that are not part of the user record
24
+ LOGIN_FIELDS = %i[session is_external_client login_mechanism credentials_seen].freeze
25
+
26
+ # @!attribute [r] user
27
+ # @return [User] The user tied to the session or the API key
28
+ auto_attr :user, type: User
29
+
30
+ # @!attribute [r] session
31
+ # @return [String] Session key, usable with the `auth` message on the push API
32
+ auto_attr :session, type: String
33
+
34
+ # @!attribute [r] is_external_client
35
+ # @return [Boolean] Whether the request was detected as coming from outside the local network
36
+ auto_attr :is_external_client, type: Types::Boolean
37
+
38
+ # @!attribute [r] login_mechanism
39
+ # @return [String, nil] How the user was authenticated, e.g. "apikey" or "password".
40
+ # Not in the 1.11.8 docs, but sent by OctoPrint 1.11.8
41
+ auto_attr :login_mechanism, type: String
42
+
43
+ # @!attribute [r] credentials_seen
44
+ # @return [String, nil] ISO 8601 time of the last credentials check, e.g. "2026-11-16T03:56:31+00:00".
45
+ # Not in the 1.11.8 docs, but sent by OctoPrint 1.11.8
46
+ auto_attr :credentials_seen, type: String
47
+
48
+ auto_initialize!
49
+
50
+ deserialize_config do
51
+ rename _is_external_client: :is_external_client,
52
+ _login_mechanism: :login_mechanism,
53
+ _credentials_seen: :credentials_seen
54
+ transform do |data|
55
+ # Everything that isn't a login field belongs to the user record
56
+ user_data = data.except(*LOGIN_FIELDS)
57
+ user_data.each_key { |key| data.delete(key) }
58
+ data[:user] = User.deserialize(user_data)
59
+ end
60
+ end
61
+ end
62
+ end
63
+ end
@@ -0,0 +1,71 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ module Octoprint
5
+ module Access
6
+ # Represents a permission in the OctoPrint access control system
7
+ #
8
+ # @example
9
+ # permission = Octoprint::Access::Permission.new(
10
+ # key: "SETTINGS",
11
+ # name: "Settings",
12
+ # dangerous: false,
13
+ # default_groups: ["admins", "operators"],
14
+ # description: "Allows access to settings",
15
+ # needs: ["CONNECTION"]
16
+ # )
17
+ class Permission
18
+ include AutoInitializable
19
+ include Deserializable
20
+
21
+ # @!attribute [r] key
22
+ # @return [String] The permission key
23
+ auto_attr :key, type: String
24
+
25
+ # @!attribute [r] name
26
+ # @return [String] The human-readable name
27
+ auto_attr :name, type: String
28
+
29
+ # @!attribute [r] dangerous
30
+ # @return [Boolean] Whether this permission is dangerous
31
+ auto_attr :dangerous, type: Types::Boolean
32
+
33
+ # @!attribute [r] default_groups
34
+ # @return [Array<String>] Groups that have this permission by default
35
+ auto_attr :default_groups, type: String, array: true
36
+
37
+ # @!attribute [r] description
38
+ # @return [String, nil] Description of the permission
39
+ auto_attr :description, type: String, nilable: true
40
+
41
+ # @!attribute [r] needs
42
+ # @return [Array<String>] Permissions this one depends on
43
+ auto_attr :needs, type: String, array: true
44
+
45
+ # @!attribute [r] needs_role
46
+ # @return [Array<String>] Roles this permission needs
47
+ auto_attr :needs_role, type: String, array: true
48
+
49
+ # @!attribute [r] plugin
50
+ # @return [String, nil] Plugin that provides this permission
51
+ auto_attr :plugin, type: String, nilable: true
52
+
53
+ # @!attribute [r] extra
54
+ # @return [Hash] Additional attributes from the API
55
+ auto_attr :extra, type: Hash
56
+
57
+ auto_initialize!
58
+
59
+ deserialize_config do
60
+ rename defaultGroups: :default_groups
61
+ transform do |data|
62
+ # Handle the needs structure which comes as a hash with role array
63
+ if data[:needs].is_a?(Hash) && data[:needs][:role]
64
+ data[:needs_role] = data[:needs][:role]
65
+ data[:needs] = [] # Set needs to empty array since API uses hash structure
66
+ end
67
+ end
68
+ end
69
+ end
70
+ end
71
+ end
@@ -0,0 +1,29 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ module Octoprint
5
+ module Access
6
+ # Provides access to the OctoPrint permissions API
7
+ #
8
+ # @see https://docs.octoprint.org/en/master/api/access.html#retrieve-a-list-of-permissions
9
+ class Permissions < BaseResource
10
+ resource_path("/api/access/permissions")
11
+
12
+ # Retrieve a list of permissions
13
+ #
14
+ # @example Get all permissions
15
+ # permissions = Octoprint::Access::Permissions.list
16
+ # permissions.each do |permission|
17
+ # puts "#{permission.key}: #{permission.name}"
18
+ # end
19
+ #
20
+ # @return [Array<Permission>] An array of Permission objects
21
+ #: -> Array[Permission]
22
+ def self.list
23
+ response = fetch_resource(deserialize: false)
24
+ permissions_data = response[:permissions] || response["permissions"] || []
25
+ permissions_data.map { |permission_data| Permission.deserialize(permission_data) }
26
+ end
27
+ end
28
+ end
29
+ end
@@ -0,0 +1,95 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ module Octoprint
5
+ module Access
6
+ # Represents a user in the OctoPrint access control system
7
+ #
8
+ # @example
9
+ # user = Octoprint::Access::User.new(
10
+ # name: "john_doe",
11
+ # active: true,
12
+ # admin: false,
13
+ # api_key: "ABC123",
14
+ # settings: {},
15
+ # groups: ["operators"],
16
+ # permissions: ["CONTROL", "MONITOR"],
17
+ # needs_role: []
18
+ # )
19
+ class User
20
+ include AutoInitializable
21
+ include Deserializable
22
+
23
+ # @!attribute [r] name
24
+ # @return [String] The user's login name
25
+ auto_attr :name, type: String
26
+
27
+ # @!attribute [r] active
28
+ # @return [Boolean] Whether the user is active
29
+ auto_attr :active, type: Types::Boolean
30
+
31
+ # @!attribute [r] admin
32
+ # @return [Boolean] Whether the user is an admin (deprecated, use groups)
33
+ auto_attr :admin, type: Types::Boolean
34
+
35
+ # @!attribute [r] api_key
36
+ # @return [String, nil] The user's API key (only in list requests)
37
+ auto_attr :api_key, type: String, nilable: true
38
+
39
+ # @!attribute [r] settings
40
+ # @return [Hash] The user's settings
41
+ auto_attr :settings, type: Hash
42
+
43
+ # @!attribute [r] groups
44
+ # @return [Array<String>] Groups the user belongs to
45
+ auto_attr :groups, type: String, array: true
46
+
47
+ # @!attribute [r] permissions
48
+ # @return [Array<String>] Effective permissions for the user
49
+ auto_attr :permissions, type: String, array: true
50
+
51
+ # @!attribute [r] needs_role
52
+ # @return [Array<String>] Roles needed by the user
53
+ auto_attr :needs_role, type: String, array: true
54
+
55
+ # @!attribute [r] needs
56
+ # @return [Hash] Needs information with groups and roles
57
+ auto_attr :needs, type: Hash
58
+
59
+ # @!attribute [r] roles
60
+ # @return [Array<String>] User roles
61
+ auto_attr :roles, type: String, array: true
62
+
63
+ # @!attribute [r] user
64
+ # @return [Boolean, nil] Whether this is a user (vs admin)
65
+ auto_attr :user, type: Types::Boolean, nilable: true
66
+
67
+ # @!attribute [r] extra
68
+ # @return [Hash] Additional attributes from the API
69
+ auto_attr :extra, type: Hash
70
+
71
+ auto_initialize!
72
+
73
+ deserialize_config do
74
+ rename apikey: :api_key
75
+ rename needsRole: :needs_role
76
+ transform do |data|
77
+ # Handle the needs structure which comes as a hash with group and role arrays
78
+ data[:needs_role] = data[:needs][:role] if data[:needs].is_a?(Hash) && data[:needs][:role]
79
+ end
80
+ end
81
+
82
+ # Convenient class method to get current user (delegates to Users.current)
83
+ #
84
+ # @example Get current user
85
+ # user = Octoprint::Access::User.current
86
+ # puts "Current user: #{user.name}"
87
+ #
88
+ # @return [User] The current user object
89
+ #: -> User
90
+ def self.current
91
+ Users.current
92
+ end
93
+ end
94
+ end
95
+ end
@@ -0,0 +1,347 @@
1
+ # typed: true
2
+ # frozen_string_literal: true
3
+
4
+ module Octoprint
5
+ # Access control: users, groups, permissions, and login/logout.
6
+ #
7
+ # @see https://docs.octoprint.org/en/1.11.8/api/access.html OctoPrint Access control API Documentation
8
+ module Access
9
+ # Provides access to the OctoPrint users API
10
+ #
11
+ # @see https://docs.octoprint.org/en/master/api/access.html#users
12
+ class Users < BaseResource
13
+ resource_path("/api/access/users")
14
+
15
+ # Retrieve a list of users
16
+ #
17
+ # Requires the SETTINGS permission.
18
+ #
19
+ # @example Get all users
20
+ # users = Octoprint::Access::Users.list
21
+ # users.each do |user|
22
+ # puts "#{user.name} - Active: #{user.active}"
23
+ # end
24
+ #
25
+ # @return [Array<User>] An array of User objects
26
+ #: -> Array[User]
27
+ def self.list
28
+ response = fetch_resource(deserialize: false)
29
+ users_data = response[:users] || response["users"] || []
30
+ users_data.map { |user_data| User.deserialize(user_data) }
31
+ end
32
+
33
+ # Add a new user
34
+ #
35
+ # Requires the SETTINGS permission and a recent credentials check.
36
+ #
37
+ # @example Create a new user
38
+ # user = Octoprint::Access::Users.add(
39
+ # name: "john_doe",
40
+ # password: "secure_password",
41
+ # active: true,
42
+ # admin: false
43
+ # )
44
+ #
45
+ # @param name [String] The user's login name
46
+ # @param password [String] The user's password
47
+ # @param active [Boolean] Whether the user should be active
48
+ # @param admin [Boolean] Whether the user should be an admin (deprecated)
49
+ # @param groups [Array<String>, nil] Groups to assign the user to
50
+ # @param permissions [Array<String>, nil] Additional permissions
51
+ # @return [Array<User>] An array of User objects
52
+ #: (
53
+ #| name: String,
54
+ #| password: String,
55
+ #| active: bool,
56
+ #| admin: bool,
57
+ #| ?groups: Array[String]?,
58
+ #| ?permissions: Array[String]?
59
+ #| ) -> Array[User]
60
+ def self.add(name:, password:, active:, admin:, groups: nil, permissions: nil)
61
+ params = {
62
+ name: name,
63
+ password: password,
64
+ active: active,
65
+ admin: admin
66
+ }
67
+ params[:groups] = groups if groups
68
+ params[:permissions] = permissions if permissions
69
+
70
+ response = post_with_hash_format(params: params)
71
+ users_data = response[:users] || response["users"] || []
72
+ users_data.map { |user_data| User.deserialize(user_data) }
73
+ end
74
+
75
+ # Retrieve a specific user
76
+ #
77
+ # Requires the SETTINGS permission.
78
+ #
79
+ # @example Get a specific user
80
+ # user = Octoprint::Access::Users.get(username: "john_doe")
81
+ #
82
+ # @param username [String] The user's login name
83
+ # @return [User] The requested user
84
+ #: (username: String) -> User
85
+ def self.get(username:)
86
+ response = fetch_resource(username, deserialize: false)
87
+ User.deserialize(response)
88
+ end
89
+
90
+ # Update an existing user
91
+ #
92
+ # Requires the SETTINGS permission and a recent credentials check.
93
+ #
94
+ # @example Update a user
95
+ # user = Octoprint::Access::Users.update(
96
+ # username: "john_doe",
97
+ # params: {
98
+ # active: false,
99
+ # groups: ["operators", "users"]
100
+ # }
101
+ # )
102
+ #
103
+ # @param username [String] The user's login name
104
+ # @param params [Hash] The attributes to update
105
+ # @return [Array<User>] The list of users
106
+ #: (username: String, params: Hash[Symbol, untyped]) -> Array[User]
107
+ def self.update(username:, params:)
108
+ path = [@path, username].join("/")
109
+ response = put_with_hash_format(path: path, params: params)
110
+
111
+ users_data = response[:users] || response["users"] || []
112
+ users_data.map { |user_data| User.deserialize(user_data) }
113
+ end
114
+
115
+ # Delete a user
116
+ #
117
+ # Requires the SETTINGS permission and a recent credentials check.
118
+ #
119
+ # @example Delete a user
120
+ # Octoprint::Access::Users.delete(username: "john_doe")
121
+ #
122
+ # @param username [String] The user's login name
123
+ # @return [void]
124
+ #: (
125
+ #| ?username: String?,
126
+ #| ?path: String?,
127
+ #| ?params: Hash[Symbol, untyped]?,
128
+ #| ?headers: Hash[Symbol, untyped]?,
129
+ #| ?options: Hash[Symbol, untyped]?
130
+ #| ) -> untyped
131
+ def self.delete(username: nil, path: nil, params: nil, headers: nil, options: nil)
132
+ if username
133
+ # User deletion case
134
+ user_path = [@path, username].join("/")
135
+ delete_resource(user_path)
136
+ nil
137
+ else
138
+ # Base case - call parent implementation
139
+ super(path: T.must(path), params: params || {}, headers: headers || {}, options: options || {})
140
+ end
141
+ end
142
+
143
+ # Delete a resource at the given path
144
+ #: (String path) -> void
145
+ def self.delete_resource(path)
146
+ client.request(
147
+ path,
148
+ {
149
+ http_method: :delete
150
+ }
151
+ )
152
+ nil
153
+ end
154
+
155
+ # Change a user's password
156
+ #
157
+ # Requires appropriate permissions based on whether changing own or other's password.
158
+ #
159
+ # @example Change a user's password
160
+ # Octoprint::Access::Users.change_password(
161
+ # username: "john_doe",
162
+ # password: "new_secure_password"
163
+ # )
164
+ #
165
+ # @param username [String] The user's login name
166
+ # @param password [String] The new password
167
+ # @return [void]
168
+ #: (username: String, password: String) -> untyped
169
+ def self.change_password(username:, password:)
170
+ path = [@path, username, "password"].join("/")
171
+ post_with_hash_format(path: path, params: { password: password })
172
+ nil
173
+ end
174
+
175
+ # Get a user's settings
176
+ #
177
+ # @example Get user settings
178
+ # settings = Octoprint::Access::Users.get_settings(username: "john_doe")
179
+ #
180
+ # @param username [String] The user's login name
181
+ # @return [Hash] The user's settings
182
+ #: (username: String) -> Hash[Symbol, untyped]
183
+ def self.get_settings(username:)
184
+ path = [username, "settings"].join("/")
185
+ fetch_resource(path, deserialize: false)
186
+ end
187
+
188
+ # Update a user's settings
189
+ #
190
+ # @example Update user settings
191
+ # settings = Octoprint::Access::Users.update_settings(
192
+ # username: "john_doe",
193
+ # settings: { interface: { color: "dark" } }
194
+ # )
195
+ #
196
+ # @param username [String] The user's login name
197
+ # @param settings [Hash] The settings to update
198
+ # @return [Hash] The updated settings
199
+ #: (username: String, settings: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
200
+ def self.update_settings(username:, settings:)
201
+ path = [@path, username, "settings"].join("/")
202
+ patch_with_hash_format(path: path, params: settings)
203
+ end
204
+
205
+ # Generate a new API key for a user
206
+ #
207
+ # Requires appropriate permissions.
208
+ #
209
+ # @example Generate new API key
210
+ # api_key = Octoprint::Access::Users.generate_api_key(username: "john_doe")
211
+ #
212
+ # @param username [String] The user's login name
213
+ # @return [String] The new API key
214
+ #: (username: String) -> String
215
+ def self.generate_api_key(username:)
216
+ path = [@path, username, "apikey"].join("/")
217
+ response = client.request(path, { http_method: :post })
218
+ response[:apikey]
219
+ end
220
+
221
+ # Delete a user's API key
222
+ #
223
+ # Requires appropriate permissions.
224
+ #
225
+ # @example Delete API key
226
+ # Octoprint::Access::Users.delete_api_key(username: "john_doe")
227
+ #
228
+ # @param username [String] The user's login name
229
+ # @return [void]
230
+ #: (username: String) -> untyped
231
+ def self.delete_api_key(username:)
232
+ path = [@path, username, "apikey"].join("/")
233
+ delete_resource(path)
234
+ nil
235
+ end
236
+
237
+ # Retrieve information about the current user
238
+ #
239
+ # @example Get current user
240
+ # user = Octoprint::Access::Users.current
241
+ # puts "Current user: #{user.name}"
242
+ #
243
+ # @return [User] The current user object
244
+ # @raise [RuntimeError] when no client is configured
245
+ #: -> User
246
+ def self.current
247
+ response = client.request("/api/currentuser", http_method: :get)
248
+ User.deserialize(response)
249
+ end
250
+
251
+ # Log in, or get the user tied to the current API key ("passive login")
252
+ #
253
+ # Without arguments, this is a passive login: OctoPrint returns the user
254
+ # tied to the client's API key, along with a session key you can send in
255
+ # the `auth` message of the push API. This is the main use case for this gem.
256
+ #
257
+ # With a username and a password, this is an active login. OctoPrint
258
+ # checks the credentials, returns the user and sets a session cookie.
259
+ # This gem only authenticates with its API key: it doesn't keep cookies,
260
+ # so the session cookie is thrown away and later requests keep using the
261
+ # API key. The returned {LoginResponse#session} is still valid for the push API.
262
+ #
263
+ # @example Passive login, to authenticate on the push API
264
+ # login = Octoprint::Access::Users.login
265
+ # login.user.name # => "sophie"
266
+ # login.session # => "5f8c1a..."
267
+ #
268
+ # @example Active login, to check a user's credentials
269
+ # login = Octoprint::Access::Users.login(username: "john_doe", password: "secret", remember: true)
270
+ # login.user.name # => "john_doe"
271
+ #
272
+ # @param username [String, nil] The user's login name. Omit for a passive login
273
+ # @param password [String, nil] The user's password. Omit for a passive login
274
+ # @param remember [Boolean] Whether OctoPrint should set a "remember me" cookie (active login only)
275
+ # @return [LoginResponse] The logged in user, the session key and whether the client is external
276
+ # @raise [ArgumentError] if only one of `username` and `password` is given,
277
+ # or if `remember` is set on a passive login
278
+ # @raise [Exceptions::AuthenticationError] if the username or password is wrong,
279
+ # the user is unknown or the account is deactivated
280
+ # @see https://docs.octoprint.org/en/1.11.8/api/general.html#login
281
+ #: (
282
+ #| ?username: String?,
283
+ #| ?password: String?,
284
+ #| ?remember: bool
285
+ #| ) -> LoginResponse
286
+ def self.login(username: nil, password: nil, remember: false)
287
+ response = client.request("/api/login", http_method: :post,
288
+ body: login_params(username, password, remember))
289
+ LoginResponse.deserialize(response)
290
+ end
291
+
292
+ # End the current login session
293
+ #
294
+ # Logout only ends a session cookie set by a browser-based login. This gem
295
+ # authenticates with its API key and doesn't keep cookies, so there is no
296
+ # session to end and the API key keeps working afterwards. It is provided
297
+ # for completeness.
298
+ #
299
+ # The docs say OctoPrint answers `204 No Content`, but OctoPrint 1.11.8
300
+ # answers `200 OK` with the guest's needs as the body. Both mean success.
301
+ #
302
+ # @example
303
+ # Octoprint::Access::Users.logout # => true
304
+ #
305
+ # @return [Boolean] true when OctoPrint accepts the logout (`200` or `204`)
306
+ # @see https://docs.octoprint.org/en/1.11.8/api/general.html#logout
307
+ #: -> bool
308
+ def self.logout # rubocop:disable Naming/PredicateMethod
309
+ client.request("/api/logout", http_method: :post)
310
+ true
311
+ end
312
+
313
+ #: (
314
+ #| String? username,
315
+ #| String? password,
316
+ #| bool remember
317
+ #| ) -> Hash[Symbol, untyped]
318
+ private_class_method def self.login_params(username, password, remember)
319
+ if username.nil? && password.nil?
320
+ raise ArgumentError, "remember only applies to an active login" if remember
321
+
322
+ return { passive: true }
323
+ end
324
+ raise ArgumentError, "username and password must be given together" if username.nil? || password.nil?
325
+
326
+ params = { user: username, pass: password }
327
+ params[:remember] = true if remember
328
+ params
329
+ end
330
+
331
+ #: (?path: String, ?params: Hash[Symbol, untyped]) -> untyped
332
+ private_class_method def self.post_with_hash_format(path: @path, params: {})
333
+ T.unsafe(client).request(path, { http_method: :post, params: params })
334
+ end
335
+
336
+ #: (?path: String, ?params: Hash[Symbol, untyped]) -> untyped
337
+ private_class_method def self.put_with_hash_format(path: @path, params: {})
338
+ T.unsafe(client).request(path, { http_method: :put, params: params })
339
+ end
340
+
341
+ #: (?path: String, ?params: Hash[Symbol, untyped]) -> untyped
342
+ private_class_method def self.patch_with_hash_format(path: @path, params: {})
343
+ T.unsafe(client).request(path, { http_method: :patch, params: params })
344
+ end
345
+ end
346
+ end
347
+ end