metapi is a client-side library to make it easier for scripts to work with the metasmoke API. It also caches responses so that only as many requests as necessary are made, instead of one per script.

The metapi.Cache class is a simple key-value based permanent cache. You can use this class to implement your own caching, if you want; otherwise, it's just used for metapi's post caching.

Constructs and returns a new clean cache object. The following are instance methods of this object:

Stores value in the cache under key. Does not expire automatically. The options object contains options that affect the operation: currently, the only supported option is overwrite (boolean), which dictates whether or not existing values should be overwritten.

Retrieves the value stored under key; this will be undefined if there is no value.

Removes any value stored under key.

You probably don't need to use this class for your own purposes, but it is returned by a metapi's API-interaction methods.

Constructs and returns a new Response object with the specified success status and data. The following are instance properties of the returned object (i.e. new metapi.Response(true, {}).success):

Boolean representing the success state of the relevant request.

Data from the relevant request. In metapi's methods, this only exists if success == true, and will contain the relevant object (i.e. posts, for requested posts).

If success is false, Response tries to parse an error_name from the passed data object, which is returned in this field.

Likewise, but with a numeric error code.

Ya need me to explain this?

This class is a wrapper around a metasmoke API filter. Given a list of fields you require (use fully-qualified database field names, like posts.id), this will construct the filter string.

Construct and return a filter object. required_fields should be an array of fields you require (again, use FQDF names). The returned object will have these properties:

An indicator of whether the filter could be created, or whether we're still waiting on data loading before that's possible. If success is false, you will have error_name, error_message, and error_code properties in addition. You can usually wait a short time and then re-call the constructor to fix issues here. If success is true, you will get the following properties:

This is the filter string itself. It's already URI-encoded, so don't double-encode. Pass this as the filter query string parameter on requests to the metasmoke API.

Equivalent to the required_fields array passed to the constructor; this is a list of fields included in the filter.

This is a dictionary of field names to bitstring indexes, which you can use to construct your own filters if you really feel like doing that. You should probably talk to someone who knows about them before you do that, though (read: Art).

Retrieves and caches a post from the metasmoke API.

Param	Description
ident	The numeric post ID (must be a number, not a string), a post URL to fetch, an array of numeric post IDs, or an array of post URLs. The arrays can't be mixed.
key	Your app's API key.
options	An options object. Anything you pass here will be added to the request URL and sent to the API; you can add a filter here, for example. Add forceReload: true to this object to bypass caching and force a new fetch of the post.
callback	A method that will be called with an array of metapi.Response objects when the operation has completed. The data param of the Response object is the post requested, as returned from the MS API.

Part of metasmoke OAuth. Once you have a code from the user (which is not part of metapi because every app needs to do this subtly differently), you can pass it here to exchange it for a write token.

Param	Description
code	The code (from metasmoke) that you've collected from the user.
key	Your app's API key.
callback	A method that will be called with a metapi.Response object when the operation has completed. The data param of the Response object will contain a token key, the value of which is the write token.

Sends feedback to the post you specify.

Param	Description
id	The post ID to send feedback to; if you don't have it, use metapi.getPost with a URL to find it.
feedback	The feedback type to send, as recognised by metasmoke.
key	Your app's API key.
token	A valid API write token.
callback	A method that will be called with a metapi.Response object when the operation has completed. The data param of the Response object contains all feedbacks on the post, as returned from the MS API.

Reports a post via the metasmoke API; this gets sent down the websocket to Smokey to be analyzed.

Param	Description
url	The URL to the post you want to report; can be in any format Smokey will recognize.
key	Your app's API key.
token	A valid API write token.
callback	A method that will be called with a metapi.Response object when the operation has completed. The data param of the Response object is an empty object, since the metasmoke API returns no useful data here.

Casts a spam flag on a post via the metasmoke API. This will fail if the user is not SE-write-authenticated; it may also fail because gremlins.

Param	Description
id	The metasmoke ID of the post you want to cast a flag on.
key	Your app's API key.
token	A valid API write token.
callback	A method that will be called with a metapi.Response object when the operation has completed. The data param of the Response object contains a backoff key, the value of which is the backoff as returned from the metasmoke API (which in turn has been passed along from the SE API). You should wait this many seconds before calling spamFlag again.