feat: add Auth#revokeTokens specs

textile/features.textile

@@ -256,6 +256,13 @@ h3(#rest-auth). Auth
 ** @(RSA16b)@ If the library is provided with a token without the corresponding @TokenDetails@, then this holds a @TokenDetails@ instance in which only the @token@ attribute is populated with that token string
 ** @(RSA16c)@ Is set with the current token (if applicable) on instantiation and each time it is replaced, whether the result of an explicit @Auth#authorize@ operation, or a library-initiated renewal resulting from expiry or a token error response
 ** @(RSA16d)@ Is @null@ if there is no current token, including after a previous token has been determined to be invalid or expired, or if the library is using basic auth
+* @(RSA17)@ @Auth#revokeTokens@ function:
+** @(RSA17a)@ Takes a @TokenRevocationTargetSpecifier@ or an array of @TokenRevocationTargetSpecifier@s and sends them in a POST request to /keys/{API_KEY_NAME}/revokeTokens, with the newBatchResponse query param set to "true", where @API_KEY_NAME@ is the API key name obtained by reading @AuthOptions#key@ up until the first @:@ character.
+** @(RSA17b)@ The @TokenRevocationTargetSpecifier@s should be mapped to strings by joining the @type@ and @value@ with a ":" character and sent in the @targets@ field of the request body
+** @(RSA17c)@ When called with an array of @TokenRevocationTargetSpecifier@s, returns an array of @BatchResult<TokenRevocationSuccessResult | TokenRevocationFailureResult>@s. When called with a single @TokenRevocationTargetSpecifier@, the REST response will be an array containing a single @BatchResult<TokenRevocationSuccessResult | TokenRevocationFailureResult>@ which may optionally be returned without the enclosing array in languages which support method overloading.
+** @(RSA17d)@ If called from a client using token authentication, should raise an @ErrorInfo@ with a @40162@ error code
+** @(RSA17e)@ If an @issuedBefore@ timestamp is supplied, it should be included in the @issuedBefore@ field of the request body
+** @(RSA17f)@ If an @allowReauthMargin@ boolean is supplied, it should be included in the @allowReauthMargin@ field of the request body
 
 h3(#rest-channels). Channels
 
@@ -1546,6 +1553,28 @@ h4. BatchPresenceFailureResult
 ** @(BGF2a)@ @channel@ string - the name of the channel
 ** @(BGF2b)@ @error@ @ErrorInfo@ - @ErrorInfo@ indicating the reason the presence request failed for the given channel, if unsuccessful
 
+h4. TokenRevocationSpecifierTarget
+
+* @(TRT1)@ Describes which tokens should be affected by a token revocation request
+* @(TRT2)@ The attributes of @TokenRevocationTargetSpecifier@ consist of:
+** @(TRT2a)@ @type@ string - the type of token revoation target specifier (eg. "clientId", "revocationKey", "channel")
+** @(TRT2b)@ @value@ string - the value of the token revocation target specifier
+
+h4. TokenRevocationSuccessResult
+
+* @(TRS1)@ Contains information about the result of a successful token revocation request for a single target specifier
+* @(TRS2)@ The attributes of @TokenRevocationSuccessResult@ consist of:
+** @(TRS2a)@ @target@ string - the target specifier
+** @(TRS2b)@ @appliesAt@ number - a timestamp at which the token revocation will take effect
+** @(TRS2c)@ @issuedBefore@ number - a timestamp for which tokens previously issued will be revoked
+
+h4. TokenRevocationFailureResult
+
+* @(TRF1)@ Contains information about the result of an unsuccessful token revocation request for a single target specifier
+* @(TRF2)@ The attributes of @TokenRevocationFailureResult@ consist of:
+** @(TRF2a)@ @target@ string - the target specifier
+** @(TRF2b)@ @error@ @ErrorInfo@ - an @ErrorInfo@ indicating the reason the token revocation request failed for the given specified
+
 h4. MessageFilter
 * @(MFI1)@ Supplies filter options to subscribe as defined in #RTL22
 * @(MFI2)@ Contains the following attributes:
@@ -1855,6 +1884,8 @@ class Auth: // RSA*
   createTokenRequest(TokenParams?, AuthOptions?) => io TokenRequest // RSA9
   requestToken(TokenParams?, AuthOptions?) => io TokenDetails // RSA8
   tokenDetails: TokenDetails? // RSA16
+  revokeTokens(TokenRevocationTargetSpecifier, issuedBefore number?, allowReauthMargin boolean?) => io BatchResult<TokenRevocationSuccessResult | TokenRevocationFailureResult> // RSA17
+  revokeTokens(TokenRevocationTargetSpecifier[], issuedBefore number?, allowReauthMargin boolean?) => io BatchResult<TokenRevocationSuccessResult | TokenRevocationFailureResult>[] // RSA17
 
 class TokenDetails: // TD*
   +fromJson(String | JsonObject) -> TokenDetails // TD7
@@ -2402,6 +2433,20 @@ class BatchPresenceSuccessResult:
 class BatchPresenceFailureResult
   channel: string // BGF2a
   error?: ErrorInfo // BGF2b
+
+class TokenRevocationTargetSpecifier:
+  type: string // TRT2a
+  value: string // TRT2b
+
+class TokenRevocationSuccessResult:
+  target: string // TRS2a
+  appliesAt: number // TRS2b
+  issuedBefore: number // TRS2c
+
+class TokenRevocationFailureResult:
+  target: string // TRF2a
+  error: ErrorInfo // TRF2b
+>>>>>>> 75f5279 (feat: add `Auth#revokeTokens` specs)
 </pre>
 
 h2(#old-specs). Old specs