@spec artifacts(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.Operations.GetApiV1UsersUserArtifacts.Response.t()}
  | {:error, ArchAstro.Error.reason()}

List a user's artifacts

Returns all artifacts owned by the specified user. Artifacts represent AI-generated or user-uploaded files associated with agent sessions, threads, or sandboxes — such as images, documents, and code outputs.

The authenticated user must be requesting their own artifacts or must have administrative access. Attempting to list artifacts for a user the caller is not authorized to access returns 403.

Results are returned in a single page without cursor pagination. Each artifact in the response reflects the state of its current version, including a short-lived signed file_url for direct download.

Successful response

@spec get(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.User.t()} | {:error, ArchAstro.Error.reason()}

Retrieve a user by ID

Returns the user identified by user. The authenticated user must share at least one team with the target user; requests for users outside any shared team are rejected with 403.

A user may always retrieve their own profile with this endpoint. Use the GET /users/me endpoint as a convenience alias for retrieving the authenticated user without specifying an ID.

The requested user object.

@spec invites(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1UsersUserInvites.Input.t()
) :: {:ok, ArchAstro.Types.UserInvite.t()} | {:error, ArchAstro.Error.reason()}

Create a user invite

Creates a new invite for the authenticated user. The invite can optionally be scoped to a specific thread, a persona, or carry arbitrary metadata. The caller receives the new invite object at HTTP 201.

The invite key is always generated server-side (192-bit URL-safe random string) and cannot be supplied by the caller.

The path :user must match the authenticated user. If a thread_id is provided, the authenticated user must have permission to invite others to that thread; team threads are not supported and return an error. Supplying a thread_id that does not exist or that belongs to a different user returns an error. If a key collision occurs during creation the call returns a 409 conflict — simply retry to generate a new key.

The newly created invite object.

@spec me(ArchAstro.Client.t()) ::
  {:ok, ArchAstro.Types.User.t()} | {:error, ArchAstro.Error.reason()}

Retrieve the current user

Returns the user associated with the authenticated session or bearer token. This is the canonical way to resolve "who am I?" after authentication.

The response includes the user's profile, notification settings, and profile picture, along with the app, organization, and sandbox the token is scoped to and their display names — enough to establish full session context in a single call. Unauthenticated requests return 401.

The authenticated user object.

@spec orgs(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.Operations.GetApiV1UsersUserOrgs.Response.t()}
  | {:error, ArchAstro.Error.reason()}

List organizations for a user

Returns the organizations the specified user belongs to. A user can belong to at most one organization, so the data array contains either zero or one items.

The authenticated viewer must have permission to inspect the target user. Returns an empty data array when the user has no organization membership.

Successful response

@spec profile(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PutApiV1UsersUserProfile.Input.t()
) :: {:ok, ArchAstro.Types.User.t()} | {:error, ArchAstro.Error.reason()}

Update the current user's profile

Updates one or more profile fields for the authenticated user. All fields are optional; omit any you do not want to change.

When profile_picture is supplied, the image is uploaded and replaces the existing picture. The previous picture is deleted after the new one is stored. Image upload failures return 422 without modifying other profile fields.

The user object with updated profile fields.