The permissions system allows you to control who has access to run commands and make changes to configuration settings.
#Basics
###Permission Ids
Each permission object has a unique id. While technically this id could be anything (minus spaces), its recommended they be in the format type.name. For example, the command to set a timeout, !settimeout, uses the permission cmd.settimeout to determine who is allowed to set a timeout's duration. Plugins may also opt to use permissions for other abilities as well, such as using a timeout.bypass permission to allow a person to bypass a timeout or even using a permissions object to filter who is included in a raffle.
###Permission Levels/Ranks Permission objects have a permission level that is based on a user's rank. These levels/ranks allow for a general level of permissions management. The level isn't a minimum or maximum rank; is actually a bitmask that specifies which individual ranks should be given a permission. A permission's 'level' is the bitwise OR of all allowed ranks. Because of this, there is no hierarchy to ranks; If you wanted, you could give a mod permission to do something that an admin can't.
The permissions manager uses Picarto's built-in chat ranks: Admin, Mod, and Picarto Admin. There is also a User rank that is used when a user doesn't fit into one of the other ranks. It's important to note that the privileged ranks can be mixed: a person can be both a Picarto Admin and a channel Admin. However, the User rank is exclusive: if you have one of the other ranks, you are not included in the User rank. When dealing with a person with multiple ranks, the permissions system is inclusive. That is, a person only needs to have one of their ranks allowed in order to have permission to do something.
###Whitelists & Blacklists Permissions objects also have a whitelist and a blacklist for more granular control. These lists identify individual users rather than a user's rank. The blacklist takes precedent over all others: if someone is on the blacklist, they are automatically denied the permission. Anyone can be put on the whitelist or blacklist, but whitelist will only acknowledge registered users (People w/ a Picarto account).
#API Usage
The API provides a permissions manager through through the api.permissions_manager interface.
###Constants
The permissions manager provides 4 constants: PERMISSION_USER, PERMISSION_ADMIN, PERMISSION_MOD, and PERMISSION_PTVADMIN. These are the ranks used in the permissions manager for a permission's level. Any function that accepts a permission level can be given more than one rank at a time by using a bitwise OR (for example: PERMISSION_USER | PERMISSION_ADMIN ).
###Methods
userHasPermission(userObject, permissionId[, defaultPermissionLevel])
Returns a boolean value indicating whether a person is allowed the requested permission
#####userObject: The data object for a user. This is the data object you get from a message event or from the User Manager.
#####permissionId: The id of the permission.
#####defaultPermissionLevel:
(optional) The default permission level to use the first time a permission is created. If omitted, the default permission level will be PERMISSION_ADMIN | PERMISSION_MOD
isOwner(userData)
Returns a boolean value indicating whether a person is the owner of the channel.
#####userObject: The data object for a user. This is the data object you get from a message event or from the User Manager.
addPermissionLevel(channel, permissionId, level)
Adds ranks to a permission's level.
#####channel: The channel where the permission will get changed.
#####permissionId: The id of the permission.
#####level: The ranks to add to the permission's level.
removePermissionLevel(channel, permissionId, level)
Removes ranks from a permission's level.
#####channel: The channel where the permission will get changed.
#####permissionId: The id of the permission.
#####level: The ranks to remove from the permission's level.
whitelistUser(channel, permissionId, username)
Adds a username to a permission's whitelist.
#####channel: The channel where the permission will get changed.
#####permissionId: The id of the permission.
#####username: The username to add to the permission's whitelist.
unwhitelistUser(channel, permissionId, username)
Removes a username from a permission's whitelist.
#####channel: The channel where the permission will get changed.
#####permissionId: The id of the permission.
#####username: The username to remove from the permission's whitelist.
blacklistUser(channel, permissionId, username)
Adds a username to a permission's blacklist.
#####channel: The channel where the permission will get changed.
#####permissionId: The id of the permission.
#####username: The username to add to the permission's blacklist.
unblacklistUser(channel, permissionId, username)
Removes a username from a permission's blacklist.
#####channel: The channel where the permission will get changed.
#####permissionId: The id of the permission.
#####username: The username to remove from the permission's blacklist.
getPerm(channel, permissionId, defaultPermissionLevel)
Returns the permission object for the specified permission. Creates the permission object if it doesn't already exist. If you make changes to this object you should call savePerms() to ensure your changes are persisted.
#####channel: The channel where the permission will gotten from.
#####permissionId: The id of the permission.
#####defaultPermissionLevel:
(optional) The default permission level to use the first time a permission is created. If omitted, the default permission level will be PERMISSION_ADMIN | PERMISSION_MOD
savePerms()
Saves all cached permissions to storage.
#Using the Permissions Manager plugin
####Adding/Removing permission levels
!perm <permissionId> <add|del> <permissionLevel>
#####permissionId: The id of the permission.
#####add|del: Whether to add or remove ranks to/from the permission
#####permissionLevel: A comma-seperated list of ranks to add to/remove from the permission
####Adding Users to a Permission's Whitelist or Blacklist
!perm <permId> <whitelist|blacklist> <usernames>
#####permissionId: The id of the permission.
#####whitelist|blacklist: Whether to add the people to the permission's whitelist or blacklist
#####usernames: A comma-seperated list of usernames to add to the permission's whitelist/blacklist
####Removing Users from a Permission's Whitelist or Blacklist
!perm <permId> <unwhitelist|unblacklist> <usernames>
#####permissionId: The id of the permission.
#####whitelist|blacklist: Whether to remove the people from the permission's whitelist or blacklist
#####usernames: A comma-seperated list of usernames to remove from the permission's whitelist/blacklist