github_api 0.12.4 → 0.13.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.
@@ -0,0 +1,129 @@
1
+ # encoding: utf-8
2
+
3
+ module Github
4
+ class Client::Orgs::Memberships < API
5
+ # List your organization memberships
6
+ #
7
+ # @see List your organization memberships
8
+ #
9
+ # @example
10
+ # github = Github.new
11
+ # github.orgs.memberships.list
12
+ #
13
+ # @api public
14
+ def list(*args)
15
+ arguments(args)
16
+
17
+ response = get_request('/user/memberships/orgs', arguments.params)
18
+ return response unless block_given?
19
+ response.each { |el| yield el }
20
+ end
21
+ alias_method :all, :list
22
+
23
+ # Get organization membership
24
+ #
25
+ # In order to get a user's membership with an organization,
26
+ # the authenticated user must be an organization owner.
27
+ #
28
+ # @see https://developer.github.com/v3/orgs/members/#get-organization-membership
29
+ # @param [String] :org
30
+ # @param [String] :username
31
+ #
32
+ # @example
33
+ # github = Github.new oauth_toke: '...'
34
+ # github.orgs.memberships.get 'orgname', username: 'piotr'
35
+ #
36
+ # Get your organization membership
37
+ #
38
+ # @see https://developer.github.com/v3/orgs/members/#get-your-organization-membership
39
+ #
40
+ # @example
41
+ # github = Github.new oauth_token
42
+ # github.orgs.memberships.get 'orgname'
43
+ #
44
+ # @api public
45
+ def get(*args)
46
+ arguments(args, required: [:org_name])
47
+ params = arguments.params
48
+
49
+ if (username = params.delete('username'))
50
+ get_request("/orgs/#{arguments.org_name}/memberships/#{username}", params)
51
+ else
52
+ get_request("/user/memberships/orgs/#{arguments.org_name}", params)
53
+ end
54
+ end
55
+ alias_method :find, :get
56
+
57
+ # Add/update user's membership with organization
58
+ #
59
+ # In order to create or update a user's membership with an organization,
60
+ # the authenticated user must be an organization owner.
61
+ #
62
+ # @see https://developer.github.com/v3/orgs/members/#add-or-update-organization-membership
63
+ #
64
+ # @param [String] :org
65
+ # @param [String] :username
66
+ # @param [Hash] options
67
+ # @option options [String] :role
68
+ # Required. The role to give the user in the organization. Can be one of:
69
+ # * admin - The user will become an owner of the organization.
70
+ # * member - The user will become a non-owner member of the organization.
71
+ #
72
+ # @example
73
+ # github = Github.new oauth_token: '...'
74
+ # github.orgs.memberships.add 'org-name', 'member-name', role: 'role'
75
+ #
76
+ # @api public
77
+ def create(*args)
78
+ arguments(args, required: [:org_name, :username]) do
79
+ assert_required :role
80
+ end
81
+
82
+ put_request("/orgs/#{arguments.org_name}/memberships/#{arguments.username}",
83
+ arguments.params)
84
+ end
85
+ alias_method :update, :create
86
+ alias_method :add, :create
87
+
88
+ # Edit your organization membership
89
+ #
90
+ # @see https://developer.github.com/v3/orgs/members/#edit-your-organization-membership
91
+ # @param [String] :org
92
+ # @param [Hash] params
93
+ # @option params [String] :state
94
+ # Required. The state that the membership should be in.
95
+ # Only "active" will be accepted.
96
+ #
97
+ # @example
98
+ # github = Github.new oauth_token: '...'
99
+ # github.orgs.memberships.edit 'org-name', state: 'active'
100
+ #
101
+ # @api public
102
+ def edit(*args)
103
+ arguments(args, required: [:org_name]) do
104
+ assert_required :state
105
+ end
106
+
107
+ patch_request("/user/memberships/orgs/#{arguments.org_name}",
108
+ arguments.params)
109
+ end
110
+
111
+ # Remove organization membership
112
+ #
113
+ # @see https://developer.github.com/v3/orgs/members/#remove-organization-membership
114
+ # @param [String] :org
115
+ # @param [String] :username
116
+ #
117
+ # @example
118
+ # github = Github.new oauth_token: '...'
119
+ # github.orgs.memberships.remove 'orgname', 'username'
120
+ #
121
+ # @api public
122
+ def delete(*args)
123
+ arguments(args, required: [:org_name, :username])
124
+
125
+ delete_request("/orgs/#{arguments.org_name}/memberships/#{arguments.username}", arguments.params)
126
+ end
127
+ alias_method :remove, :delete
128
+ end # Client::Orgs::Memberships
129
+ end # Github
@@ -1,16 +1,10 @@
1
1
  # encoding: utf-8
2
2
 
3
3
  module Github
4
+ # All actions against teams require at a minimum an authenticated user
5
+ # who is a member of the owner's team in the :org being managed.
6
+ # Api calls that require explicit permissions are noted.
4
7
  class Client::Orgs::Teams < API
5
- # All actions against teams require at a minimum an authenticated user
6
- # who is a member of the owner’s team in the :org being managed.
7
- # Api calls that require explicit permissions are noted.
8
-
9
- VALID_TEAM_PARAM_NAMES = %w[ name repo_names permission ].freeze
10
- VALID_TEAM_PARAM_VALUES = {
11
- 'permission' => %w[ pull push admin ].freeze
12
- }
13
-
14
8
  # List user teams
15
9
  #
16
10
  # List all of the teams across all of the organizations
@@ -23,6 +17,8 @@ module Github
23
17
  #
24
18
  # List teams
25
19
  #
20
+ # @see https://developer.github.com/v3/orgs/teams/#list-teams
21
+ #
26
22
  # @example
27
23
  # github = Github.new oauth_token: '...'
28
24
  # github.orgs.teams.list org: 'org-name'
@@ -31,18 +27,20 @@ module Github
31
27
  def list(*args)
32
28
  params = arguments(args).params
33
29
 
34
- response = if org = params.delete('org')
35
- get_request("/orgs/#{org}/teams", params)
30
+ if (org = params.delete('org'))
31
+ response = get_request("/orgs/#{org}/teams", params)
36
32
  else
37
- get_request("/user/teams", params)
33
+ response = get_request('/user/teams', params)
38
34
  end
39
35
  return response unless block_given?
40
36
  response.each { |el| yield el }
41
37
  end
42
- alias :all :list
38
+ alias_method :all, :list
43
39
 
44
40
  # Get a team
45
41
  #
42
+ # @see https://developer.github.com/v3/orgs/teams/#get-team
43
+ #
46
44
  # @example
47
45
  # github = Github.new oauth_token: '...'
48
46
  # github.orgs.teams.get 'team-id'
@@ -53,18 +51,28 @@ module Github
53
51
 
54
52
  get_request("/teams/#{arguments.id}", arguments.params)
55
53
  end
56
- alias :find :get
54
+ alias_method :find, :get
57
55
 
58
56
  # Create a team
59
57
  #
60
58
  # In order to create a team, the authenticated user must be an owner of :org
61
59
  #
60
+ # @see https://developer.github.com/v3/orgs/teams/#create-team
61
+ #
62
62
  # @param [Hash] params
63
- # @input params [String] :name
63
+ # @option params [String] :name
64
64
  # Required. The name of the team
65
- # @input params [Array[String]] :repo_names
65
+ # @option params [String] :description
66
+ # The description of the team.
67
+ # @option params [Array[String]] :repo_names
66
68
  # The repositories to add the team to.
67
- # @input params [String] :permission
69
+ # @option params [String] :privacy
70
+ # The level of privacy this team should have. Can be one of:
71
+ # * secret - only visible to organization owners and
72
+ # members of this team.
73
+ # * closed - visible to all members of this organization.
74
+ # Default: secret
75
+ # @option params [String] :permission
68
76
  # The permission to grant the team. Can be one of:
69
77
  # * pull - team members can pull, but not push or
70
78
  # administor this repositories.
@@ -86,9 +94,7 @@ module Github
86
94
  # @api public
87
95
  def create(*args)
88
96
  arguments(args, required: [:org_name]) do
89
- permit VALID_TEAM_PARAM_NAMES
90
- assert_values VALID_TEAM_PARAM_VALUES
91
- assert_required %w[name]
97
+ assert_required %w(name)
92
98
  end
93
99
 
94
100
  post_request("/orgs/#{arguments.org_name}/teams", arguments.params)
@@ -99,10 +105,20 @@ module Github
99
105
  # In order to edit a team, the authenticated user must be an owner
100
106
  # of the org that the team is associated with.
101
107
  #
108
+ # @see https://developer.github.com/v3/orgs/teams/#edit-team
109
+ #
102
110
  # @param [Hash] params
103
- # @input params [String] :name
111
+ # @option params [String] :name
104
112
  # The repositories to add the team to.
105
- # @input params [String] :permission
113
+ # @option params [String] :description
114
+ # The description of the team.
115
+ # @option params [String] :privacy
116
+ # The level of privacy this team should have. Can be one of:
117
+ # * secret - only visible to organization owners and
118
+ # members of this team.
119
+ # * closed - visible to all members of this organization.
120
+ # Default: secret
121
+ # @option params [String] :permission
106
122
  # The permission to grant the team. Can be one of:
107
123
  # * pull - team members can pull, but not push or
108
124
  # administor this repositories.
@@ -121,9 +137,7 @@ module Github
121
137
  # @api public
122
138
  def edit(*args)
123
139
  arguments(args, required: [:id]) do
124
- permit VALID_TEAM_PARAM_NAMES
125
- assert_values VALID_TEAM_PARAM_VALUES
126
- assert_required %w[name]
140
+ assert_required %w(name)
127
141
  end
128
142
 
129
143
  patch_request("/teams/#{arguments.id}", arguments.params)
@@ -131,6 +145,8 @@ module Github
131
145
 
132
146
  # Delete a team
133
147
  #
148
+ # @see https://developer.github.com/v3/orgs/teams/#delete-team
149
+ #
134
150
  # In order to delete a team, the authenticated user must be an owner
135
151
  # of the org that the team is associated with
136
152
  #
@@ -138,18 +154,23 @@ module Github
138
154
  # github = Github.new oauth_token: '...'
139
155
  # github.orgs.teams.delete 'team-id'
140
156
  #
157
+ # @api public
141
158
  def delete(*args)
142
159
  arguments(args, required: [:id])
143
160
 
144
161
  delete_request("/teams/#{arguments.id}", arguments.params)
145
162
  end
146
- alias :remove :delete
163
+ alias_method :remove, :delete
147
164
 
148
165
  # List team members
149
166
  #
150
167
  # In order to list members in a team, the authenticated user
151
168
  # must be a member of the team.
152
169
  #
170
+ # @see https://developer.github.com/v3/orgs/teams/#list-team-members
171
+ #
172
+ # @param [Integer] :team_id
173
+ #
153
174
  # @example
154
175
  # github = Github.new oauth_token: '...'
155
176
  # github.orgs.teams.list_members 'team-id'
@@ -157,25 +178,30 @@ module Github
157
178
  #
158
179
  # @api public
159
180
  def list_members(*args)
160
- arguments(args, required: [:id])
181
+ arguments(args, required: [:team_id])
161
182
 
162
- response = get_request("/teams/#{arguments.id}/members", arguments.params)
183
+ response = get_request("/teams/#{arguments.team_id}/members", arguments.params)
163
184
  return response unless block_given?
164
185
  response.each { |el| yield el }
165
186
  end
166
- alias :all_members :list_members
187
+ alias_method :all_members, :list_members
167
188
 
168
189
  # Check if a user is a member of a team
169
190
  #
191
+ # @see https://developer.github.com/v3/orgs/teams/#get-team-member
192
+ #
193
+ # @param [Integer] :team_id
194
+ # @param [String] :username
195
+ #
170
196
  # @example
171
197
  # github = Github.new oauth_token: '...'
172
198
  # github.orgs.teams.team_member? 'team-id', 'user-name'
173
199
  #
174
200
  # @api public
175
201
  def team_member?(*args)
176
- arguments(args, required: [:id, :user])
202
+ arguments(args, required: [:team_id, :user])
177
203
 
178
- response = get_request("/teams/#{arguments.id}/members/#{arguments.user}", arguments.params)
204
+ response = get_request("/teams/#{arguments.team_id}/members/#{arguments.user}", arguments.params)
179
205
  response.status == 204
180
206
  rescue Github::Error::NotFound
181
207
  false
@@ -184,7 +210,7 @@ module Github
184
210
  # Add a team member
185
211
  #
186
212
  # In order to add a user to a team, the authenticated user must
187
- # have admin permissions to the team or be an owner of the org
213
+ # have 'admin' permissions to the team or be an owner of the org
188
214
  # that the team is associated with.
189
215
  #
190
216
  # @example
@@ -195,14 +221,17 @@ module Github
195
221
  def add_member(*args)
196
222
  arguments(args, required: [:id, :user])
197
223
 
198
- put_request("/teams/#{arguments.id}/members/#{arguments.user}", arguments.params)
224
+ put_request("/teams/#{arguments.id}/members/#{arguments.user}",
225
+ arguments.params)
199
226
  end
200
- alias :add_team_member :add_member
227
+ alias_method :add_team_member, :add_member
201
228
 
202
229
  # Remove a team member
203
230
  #
231
+ # @see https://developer.github.com/v3/orgs/teams/#remove-team-member
232
+ #
204
233
  # In order to remove a user from a team, the authenticated user must
205
- # have admin permissions to the team or be an owner of the org that
234
+ # have 'admin' permissions to the team or be an owner of the org that
206
235
  # the team is associated with.
207
236
  # note: This does not delete the user, it just remove them from the team.
208
237
  #
@@ -214,12 +243,91 @@ module Github
214
243
  def remove_member(*args)
215
244
  arguments(args, required: [:id, :user])
216
245
 
217
- delete_request("/teams/#{arguments.id}/members/#{arguments.user}", arguments.params)
246
+ delete_request("/teams/#{arguments.id}/members/#{arguments.user}",
247
+ arguments.params)
248
+ end
249
+ alias_method :remove_team_member, :remove_member
250
+
251
+ # Get team membership
252
+ #
253
+ # In order to get a user's membership with a team,
254
+ # the team must be visible to the authenticated user.
255
+ #
256
+ # @see https://developer.github.com/v3/orgs/teams/#get-team-membership
257
+ #
258
+ # @param [Integer] :team_id
259
+ # @param [String] :username
260
+ #
261
+ # @example
262
+ # github = Github.new oauth_token: '...'
263
+ # github.orgs.teams.team_membership 'team-id', 'username'
264
+ #
265
+ # @api public
266
+ def team_membership(*args)
267
+ arguments(args, required: [:team_id, :username])
268
+
269
+ get_request("/teams/#{arguments.team_id}/memberships/#{arguments.username}",
270
+ arguments.params)
271
+ end
272
+
273
+ # Add a team membership
274
+ #
275
+ # In order to add a user to a team, the authenticated user must
276
+ # have 'admin' permissions to the team or be an owner of the org
277
+ # that the team is associated with.
278
+ #
279
+ # @see https://developer.github.com/v3/orgs/teams/#add-team-membership
280
+ #
281
+ # @param [Integer] :team_id
282
+ # @param [String] :username
283
+ # @param [Hash] :params
284
+ # @option params [String] :role
285
+ # The role that this user should have in the team. Can be one of:
286
+ # * member - a normal member of the team.
287
+ # * maintainer - a team maintainer. Able to add/remove
288
+ # other team members, promote other team members to
289
+ # team maintainer, and edit the team's name and description.
290
+ # Default: member
291
+ #
292
+ # @example
293
+ # github = Github.new oauth_token: '...'
294
+ # github.orgs.teams.add_membership 'team-id', 'user-name'
295
+ #
296
+ # @api public
297
+ def add_membership(*args)
298
+ arguments(args, required: [:team_id, :user])
299
+
300
+ put_request("/teams/#{arguments.team_id}/memberships/#{arguments.user}",
301
+ arguments.params)
218
302
  end
219
- alias :remove_team_member :remove_member
303
+ alias_method :add_team_membership, :add_membership
304
+
305
+ # Remove a team membership
306
+ #
307
+ # In order to remove a user from a team, the authenticated user must
308
+ # have 'admin' permissions to the team or be an owner of the org that
309
+ # the team is associated with.
310
+ # note: This does not delete the user, it just remove them from the team.
311
+ #
312
+ # @see https://developer.github.com/v3/orgs/teams/#remove-team-membership
313
+ #
314
+ # @example
315
+ # github = Github.new oauth_token: '...'
316
+ # github.orgs.teams.remove_membership 'team-id', 'user-name'
317
+ #
318
+ # @api public
319
+ def remove_membership(*args)
320
+ arguments(args, required: [:team_id, :user])
321
+
322
+ delete_request("/teams/#{arguments.team_id}/memberships/#{arguments.user}",
323
+ arguments.params)
324
+ end
325
+ alias_method :remove_team_membership, :remove_membership
220
326
 
221
327
  # List team repositories
222
328
  #
329
+ # @see https://developer.github.com/v3/orgs/teams/#list-team-repos
330
+ #
223
331
  # @example
224
332
  # github = Github.new oauth_token: '...'
225
333
  # github.orgs.teams.list_repos 'team-id'
@@ -232,10 +340,12 @@ module Github
232
340
  return response unless block_given?
233
341
  response.each { |el| yield el }
234
342
  end
235
- alias :repos :list_repos
343
+ alias_method :repos, :list_repos
236
344
 
237
345
  # Check if a repository belongs to a team
238
346
  #
347
+ # @see https://developer.github.com/v3/orgs/teams/#get-team-repo
348
+ #
239
349
  # @example
240
350
  # github = Github.new oauth_token: '...'
241
351
  # github.orgs.teams.team_repo? 'team-id', 'user-name', 'repo-name'
@@ -249,7 +359,7 @@ module Github
249
359
  rescue Github::Error::NotFound
250
360
  false
251
361
  end
252
- alias :team_repository? :team_repo?
362
+ alias_method :team_repository?, :team_repo?
253
363
 
254
364
  # Add a team repository
255
365
  #
@@ -258,9 +368,11 @@ module Github
258
368
  # must be owned by the organization, or a direct for of a repo owned
259
369
  # by the organization.
260
370
  #
371
+ # @see https://developer.github.com/v3/orgs/teams/#add-team-repo
372
+ #
261
373
  # @example
262
- # github = Github.new oauth_token: '...'
263
- # github.orgs.teams.add_repo 'team-id', 'user-name', 'repo-name'
374
+ # github = Github.new oauth_token: '...'
375
+ # github.orgs.teams.add_repo 'team-id', 'user-name', 'repo-name'
264
376
  #
265
377
  # @api public
266
378
  def add_repo(*args)
@@ -268,7 +380,7 @@ module Github
268
380
 
269
381
  put_request("/teams/#{arguments.id}/repos/#{arguments.user}/#{arguments.repo}", arguments.params)
270
382
  end
271
- alias :add_repository :add_repo
383
+ alias_method :add_repository, :add_repo
272
384
 
273
385
  # Remove a team repository
274
386
  #
@@ -276,6 +388,8 @@ module Github
276
388
  # an owner of the org that the team is associated with.
277
389
  # note: This does not delete the repo, it just removes it from the team.
278
390
  #
391
+ # @see https://developer.github.com/v3/orgs/teams/#remove-team-repo
392
+ #
279
393
  # @example
280
394
  # github = Github.new oauth_token: '...'
281
395
  # github.orgs.teams.remove_repo 'team-id', 'user-name', 'repo-name'
@@ -286,6 +400,6 @@ module Github
286
400
 
287
401
  delete_request("/teams/#{arguments.id}/repos/#{arguments.user}/#{arguments.repo}", arguments.params)
288
402
  end
289
- alias :remove_repository :remove_repo
403
+ alias_method :remove_repository, :remove_repo
290
404
  end # Client::Orgs::Teams
291
405
  end # Github