Posts and Post-like Objects

The below are the basic Post and Post-like objects that make up a Provider. All Providers should offer a Post at the very least. Forum-like providers are likely to offer at least a Topic if not a Category. Chat-like providers may offer a "Topic" as a container for Posts that is analogous to a "Room" on IRC.

Post

All providers should offer a Post object, but the semantic meaning of what a Post is depends on the provider. In general, a "post" is a single entry into the system by a single user. In a chatlike provider, it will be a single message.

Post object: Properties

The following properties are assumed to exist, either as plain objects or via getters:

Post object: Expensive properties

The following methods each return a Promise for the property that they encapsulate. They should reject if no such property can exist.

Post object: actions

The following actions are assumed to be available to be performed on a Post. Each should act upon the actual post in the system, and return a Promise that will resolve if the action completes or reject if it does not.

Static: reply

A static method should be provided to allow for replying to arbitrary posts. It will be given three arguments: the topic ID to reply to (if any), the post ID to reply to (if any), and the content to submit. One or both of topic ID and post ID will be supplied.

This method should return a promise that will resolve to the newly created Post object.

Static: get

A static method should be provided to allow for retrieving arbitrary posts. It will be given one arguments: the primary identifier for the post.

This method should return a promise that will resolve to the requested Post object.

Static: parse

A static method should be provided to allow for parsing arbitrary posts. It will be given one arguments: the raw payload retrieved from the API for the forum.

This method should return a promise that will resolve to the requested Post object.

Static: preview

A static method should be provided to allow for previewing post content. It will be given one arguments: the content intended to be submitted as a new post.

This method should return a promise that will resolve to a string that will include any modifications done by the server upon submit.

Topic

Many providers offer a Topic object; like the Post, the semantic meaning of what a Topic is depends on the provider. In general, a "topic" is a collection of posts by potentially a multitude of users.

Topic object: Properties

The following properties are assumed to exist, either as plain objects or via getters:

Topic object: Expensive properties

The following methods each return a Promise for the property that they encapsulate. They should reject if no such property can exist.

Topic object: iterator functions

The following methods each take a function that shall be applied to the relevant Post objects inside the Topic, and return a Promise that resolves when the iteration is done.

Static versions of each of these functions should also exist. Each of them take a topic identifier as well as the function for iteration.

Topic object: actions

The following actions are assumed to be available to be performed on a Post. Each should act upon the actual post in the system, and return a Promise that will resolve if the action completes or reject if it does not.

Static: get

A static method should be provided to allow for retrieving arbitrary topics. It will be given one argument: the primary identifier for the topic.

This method should return a promise that will resolve to the requested Topic object.

Static: parse

A static method should be provided to allow for parsing arbitrary topics. It will be given one arguments: the raw payload retrieved from the API.

This method should return a promise that will resolve to the requested Topic object.

Category

A Category is an optional third level of organization; a Category contains Topics the way a Topic contains Posts. A Category may optionally also contain other Categories.

Category object: Properties

The following properties are assumed to exist, either as plain objects or via getters:

Category object: Expensive properties

The following methods each return a Promise for the property that they encapsulate. They should reject if no such property can exist.

Category object: iterator functions

The following methods each take a function that shall be applied to the relevant Post objects inside the Topic, and return a Promise that resolves when the iteration is done.

Static versions of each of these functions should also exist. Each of them take a Category identifier as well as the function for iteration.

Topic object: actions

The following actions are assumed to be available to be performed on a Post. Each should act upon the actual post in the system, and return a Promise that will resolve if the action completes or reject if it does not.

Static: get

A static method should be provided to allow for retrieving arbitrary Categories. It will be given one argument: the primary identifier for the Category.

This method should return a promise that will resolve to the requested Category object.

Static: parse

A static method should be provided to allow for parsing arbitrary Categories. It will be given one arguments: the raw payload retrieved from the API.

This method should return a promise that will resolve to the requested Category object.