1import type * as cip from "@distilled.cloud/aws/cognito-identity-provider";
2import type * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { UserPool } from "./UserPool.ts";
5
6export interface AdminCreateUserRequest extends Omit<
7 cip.AdminCreateUserRequest,
8 "UserPoolId"
9> {}
10export interface AdminGetUserRequest extends Omit<
11 cip.AdminGetUserRequest,
12 "UserPoolId"
13> {}
14export interface AdminSetUserPasswordRequest extends Omit<
15 cip.AdminSetUserPasswordRequest,
16 "UserPoolId"
17> {}
18export interface AdminUpdateUserAttributesRequest extends Omit<
19 cip.AdminUpdateUserAttributesRequest,
20 "UserPoolId"
21> {}
22export interface AdminDeleteUserRequest extends Omit<
23 cip.AdminDeleteUserRequest,
24 "UserPoolId"
25> {}
26export interface AdminConfirmSignUpRequest extends Omit<
27 cip.AdminConfirmSignUpRequest,
28 "UserPoolId"
29> {}
30export interface AdminDisableUserRequest extends Omit<
31 cip.AdminDisableUserRequest,
32 "UserPoolId"
33> {}
34export interface AdminEnableUserRequest extends Omit<
35 cip.AdminEnableUserRequest,
36 "UserPoolId"
37> {}
38export interface AdminResetUserPasswordRequest extends Omit<
39 cip.AdminResetUserPasswordRequest,
40 "UserPoolId"
41> {}
42export interface AdminInitiateAuthRequest extends Omit<
43 cip.AdminInitiateAuthRequest,
44 "UserPoolId"
45> {}
46export interface AdminRespondToAuthChallengeRequest extends Omit<
47 cip.AdminRespondToAuthChallengeRequest,
48 "UserPoolId"
49> {}
50export interface AdminUserGlobalSignOutRequest extends Omit<
51 cip.AdminUserGlobalSignOutRequest,
52 "UserPoolId"
53> {}
54export interface AdminAddUserToGroupRequest extends Omit<
55 cip.AdminAddUserToGroupRequest,
56 "UserPoolId"
57> {}
58export interface AdminRemoveUserFromGroupRequest extends Omit<
59 cip.AdminRemoveUserFromGroupRequest,
60 "UserPoolId"
61> {}
62export interface ListUsersRequest extends Omit<
63 cip.ListUsersRequest,
64 "UserPoolId"
65> {}
66export interface ListUsersInGroupRequest extends Omit<
67 cip.ListUsersInGroupRequest,
68 "UserPoolId"
69> {}
70export interface AdminDeleteUserAttributesRequest extends Omit<
71 cip.AdminDeleteUserAttributesRequest,
72 "UserPoolId"
73> {}
74export interface AdminListGroupsForUserRequest extends Omit<
75 cip.AdminListGroupsForUserRequest,
76 "UserPoolId"
77> {}
78export interface AdminSetUserMFAPreferenceRequest extends Omit<
79 cip.AdminSetUserMFAPreferenceRequest,
80 "UserPoolId"
81> {}
82export interface AdminLinkProviderForUserRequest extends Omit<
83 cip.AdminLinkProviderForUserRequest,
84 "UserPoolId"
85> {}
86export interface AdminDisableProviderForUserRequest extends Omit<
87 cip.AdminDisableProviderForUserRequest,
88 "UserPoolId"
89> {}
90export interface AdminGetDeviceRequest extends Omit<
91 cip.AdminGetDeviceRequest,
92 "UserPoolId"
93> {}
94export interface AdminListDevicesRequest extends Omit<
95 cip.AdminListDevicesRequest,
96 "UserPoolId"
97> {}
98export interface AdminForgetDeviceRequest extends Omit<
99 cip.AdminForgetDeviceRequest,
100 "UserPoolId"
101> {}
102export interface AdminUpdateDeviceStatusRequest extends Omit<
103 cip.AdminUpdateDeviceStatusRequest,
104 "UserPoolId"
105> {}
106export interface AdminListUserAuthEventsRequest extends Omit<
107 cip.AdminListUserAuthEventsRequest,
108 "UserPoolId"
109> {}
110export interface AdminUpdateAuthEventFeedbackRequest extends Omit<
111 cip.AdminUpdateAuthEventFeedbackRequest,
112 "UserPoolId"
113> {}
114export interface ListGroupsRequest extends Omit<
115 cip.ListGroupsRequest,
116 "UserPoolId"
117> {}
118
119/**
120 * The typed client returned by binding {@link UserPoolAdmin} to a
121 * `UserPool`. Every method automatically injects the user pool ID and is
122 * authorized by IAM (`cognito-idp:Admin*` on the pool ARN).
123 */
124export interface UserPoolAdminClient {
125 /** Create a user as an administrator (optionally suppressing the invite). */
126 adminCreateUser: (
127 request: AdminCreateUserRequest,
128 ) => Effect.Effect<cip.AdminCreateUserResponse, cip.AdminCreateUserError>;
129 /** Fetch a user's profile and status by username. */
130 adminGetUser: (
131 request: AdminGetUserRequest,
132 ) => Effect.Effect<cip.AdminGetUserResponse, cip.AdminGetUserError>;
133 /** Set a user's password (permanent or temporary). */
134 adminSetUserPassword: (
135 request: AdminSetUserPasswordRequest,
136 ) => Effect.Effect<
137 cip.AdminSetUserPasswordResponse,
138 cip.AdminSetUserPasswordError
139 >;
140 /** Update (or add) user attributes as an administrator. */
141 adminUpdateUserAttributes: (
142 request: AdminUpdateUserAttributesRequest,
143 ) => Effect.Effect<
144 cip.AdminUpdateUserAttributesResponse,
145 cip.AdminUpdateUserAttributesError
146 >;
147 /** Delete a user as an administrator. */
148 adminDeleteUser: (
149 request: AdminDeleteUserRequest,
150 ) => Effect.Effect<cip.AdminDeleteUserResponse, cip.AdminDeleteUserError>;
151 /** Confirm a user's sign-up without a confirmation code. */
152 adminConfirmSignUp: (
153 request: AdminConfirmSignUpRequest,
154 ) => Effect.Effect<
155 cip.AdminConfirmSignUpResponse,
156 cip.AdminConfirmSignUpError
157 >;
158 /** Disable a user (prevents sign-in and revokes tokens). */
159 adminDisableUser: (
160 request: AdminDisableUserRequest,
161 ) => Effect.Effect<cip.AdminDisableUserResponse, cip.AdminDisableUserError>;
162 /** Re-enable a disabled user. */
163 adminEnableUser: (
164 request: AdminEnableUserRequest,
165 ) => Effect.Effect<cip.AdminEnableUserResponse, cip.AdminEnableUserError>;
166 /** Force a password reset on next sign-in. */
167 adminResetUserPassword: (
168 request: AdminResetUserPasswordRequest,
169 ) => Effect.Effect<
170 cip.AdminResetUserPasswordResponse,
171 cip.AdminResetUserPasswordError
172 >;
173 /** Start an auth flow with admin credentials (e.g. `ADMIN_USER_PASSWORD_AUTH`). */
174 adminInitiateAuth: (
175 request: AdminInitiateAuthRequest,
176 ) => Effect.Effect<cip.AdminInitiateAuthResponse, cip.AdminInitiateAuthError>;
177 /** Answer an auth challenge from `adminInitiateAuth`. */
178 adminRespondToAuthChallenge: (
179 request: AdminRespondToAuthChallengeRequest,
180 ) => Effect.Effect<
181 cip.AdminRespondToAuthChallengeResponse,
182 cip.AdminRespondToAuthChallengeError
183 >;
184 /** Sign a user out of all devices. */
185 adminUserGlobalSignOut: (
186 request: AdminUserGlobalSignOutRequest,
187 ) => Effect.Effect<
188 cip.AdminUserGlobalSignOutResponse,
189 cip.AdminUserGlobalSignOutError
190 >;
191 /** Add a user to a group. */
192 adminAddUserToGroup: (
193 request: AdminAddUserToGroupRequest,
194 ) => Effect.Effect<
195 cip.AdminAddUserToGroupResponse,
196 cip.AdminAddUserToGroupError
197 >;
198 /** Remove a user from a group. */
199 adminRemoveUserFromGroup: (
200 request: AdminRemoveUserFromGroupRequest,
201 ) => Effect.Effect<
202 cip.AdminRemoveUserFromGroupResponse,
203 cip.AdminRemoveUserFromGroupError
204 >;
205 /** List users in the pool (optionally filtered). */
206 listUsers: (
207 request?: ListUsersRequest,
208 ) => Effect.Effect<cip.ListUsersResponse, cip.ListUsersError>;
209 /** List the users in a group. */
210 listUsersInGroup: (
211 request: ListUsersInGroupRequest,
212 ) => Effect.Effect<cip.ListUsersInGroupResponse, cip.ListUsersInGroupError>;
213 /** Delete attributes from a user's profile as an administrator. */
214 adminDeleteUserAttributes: (
215 request: AdminDeleteUserAttributesRequest,
216 ) => Effect.Effect<
217 cip.AdminDeleteUserAttributesResponse,
218 cip.AdminDeleteUserAttributesError
219 >;
220 /** List the groups a user belongs to. */
221 adminListGroupsForUser: (
222 request: AdminListGroupsForUserRequest,
223 ) => Effect.Effect<
224 cip.AdminListGroupsForUserResponse,
225 cip.AdminListGroupsForUserError
226 >;
227 /** Set a user's MFA preferences (SMS / TOTP / email) as an administrator. */
228 adminSetUserMFAPreference: (
229 request: AdminSetUserMFAPreferenceRequest,
230 ) => Effect.Effect<
231 cip.AdminSetUserMFAPreferenceResponse,
232 cip.AdminSetUserMFAPreferenceError
233 >;
234 /** Link a federated identity to an existing native user. */
235 adminLinkProviderForUser: (
236 request: AdminLinkProviderForUserRequest,
237 ) => Effect.Effect<
238 cip.AdminLinkProviderForUserResponse,
239 cip.AdminLinkProviderForUserError
240 >;
241 /** Unlink a federated identity from a user. */
242 adminDisableProviderForUser: (
243 request: AdminDisableProviderForUserRequest,
244 ) => Effect.Effect<
245 cip.AdminDisableProviderForUserResponse,
246 cip.AdminDisableProviderForUserError
247 >;
248 /** Fetch one of a user's remembered devices. */
249 adminGetDevice: (
250 request: AdminGetDeviceRequest,
251 ) => Effect.Effect<cip.AdminGetDeviceResponse, cip.AdminGetDeviceError>;
252 /** List a user's remembered devices. */
253 adminListDevices: (
254 request: AdminListDevicesRequest,
255 ) => Effect.Effect<cip.AdminListDevicesResponse, cip.AdminListDevicesError>;
256 /** Forget (deregister) one of a user's remembered devices. */
257 adminForgetDevice: (
258 request: AdminForgetDeviceRequest,
259 ) => Effect.Effect<cip.AdminForgetDeviceResponse, cip.AdminForgetDeviceError>;
260 /** Mark a user's device as remembered or not remembered. */
261 adminUpdateDeviceStatus: (
262 request: AdminUpdateDeviceStatusRequest,
263 ) => Effect.Effect<
264 cip.AdminUpdateDeviceStatusResponse,
265 cip.AdminUpdateDeviceStatusError
266 >;
267 /** List a user's sign-in auth events (threat protection history). */
268 adminListUserAuthEvents: (
269 request: AdminListUserAuthEventsRequest,
270 ) => Effect.Effect<
271 cip.AdminListUserAuthEventsResponse,
272 cip.AdminListUserAuthEventsError
273 >;
274 /** Provide valid/invalid feedback on a user's auth event. */
275 adminUpdateAuthEventFeedback: (
276 request: AdminUpdateAuthEventFeedbackRequest,
277 ) => Effect.Effect<
278 cip.AdminUpdateAuthEventFeedbackResponse,
279 cip.AdminUpdateAuthEventFeedbackError
280 >;
281 /** List the groups in the pool. */
282 listGroups: (
283 request?: ListGroupsRequest,
284 ) => Effect.Effect<cip.ListGroupsResponse, cip.ListGroupsError>;
285}
286
287/**
288 * Runtime binding for administrative Cognito user pool operations.
289 *
290 * Bind this to a `UserPool` inside a function runtime to get a typed client
291 * for user management and admin auth flows. The binding grants the
292 * corresponding `cognito-idp:*` IAM actions scoped to the pool's ARN and
293 * injects the pool ID into every call.
294 * ### Managing Users
295 * **Example:** Create a User with a Permanent Password
296 * ```typescript
297 * const admin = yield* Cognito.UserPoolAdmin(pool);
298 *
299 * yield* admin.adminCreateUser({
300 * Username: "user@example.com",
301 * MessageAction: "SUPPRESS",
302 * UserAttributes: [
303 * { Name: "email", Value: "user@example.com" },
304 * { Name: "email_verified", Value: "true" },
305 * ],
306 * });
307 * yield* admin.adminSetUserPassword({
308 * Username: "user@example.com",
309 * Password: "Sup3r-secret!",
310 * Permanent: true,
311 * });
312 * ```
313 *
314 * **Example:** Look Up and Delete a User
315 * ```typescript
316 * const user = yield* admin.adminGetUser({ Username: "user@example.com" });
317 * yield* admin.adminDeleteUser({ Username: "user@example.com" });
318 * ```
319 *
320 * ### Groups
321 * **Example:** Manage Group Membership
322 * ```typescript
323 * yield* admin.adminAddUserToGroup({
324 * Username: "user@example.com",
325 * GroupName: "Admins",
326 * });
327 * const admins = yield* admin.listUsersInGroup({ GroupName: "Admins" });
328 * const groups = yield* admin.adminListGroupsForUser({
329 * Username: "user@example.com",
330 * });
331 * ```
332 *
333 * ### Federation and Devices
334 * **Example:** Link a Federated Identity to a Native User
335 * ```typescript
336 * yield* admin.adminLinkProviderForUser({
337 * DestinationUser: {
338 * ProviderName: "Cognito",
339 * ProviderAttributeValue: "user@example.com",
340 * },
341 * SourceUser: {
342 * ProviderName: "Google",
343 * ProviderAttributeName: "Cognito_Subject",
344 * ProviderAttributeValue: googleSub,
345 * },
346 * });
347 * ```
348 *
349 * **Example:** List a User's Remembered Devices
350 * ```typescript
351 * const devices = yield* admin.adminListDevices({
352 * Username: "user@example.com",
353 * });
354 * ```
355 *
356 * @binding
357 */
358export interface UserPoolAdmin extends Binding.Service<
359 UserPoolAdmin,
360 "AWS.Cognito.UserPoolAdmin",
361 <P extends UserPool>(pool: P) => Effect.Effect<UserPoolAdminClient>
362> {}
363export const UserPoolAdmin = Binding.Service<UserPoolAdmin>(
364 "AWS.Cognito.UserPoolAdmin",
365);