Codec.ActivityStream

This is an interface to ActivityStreams that simply wraps an underlying aeson Object, and exposes a set of convenient lenses to access the values inside. If an aeson object appears wrapped in some respective wrapper, it will necessarily contain the obligatory values for that type (e.g. an Activity is guaranteed to have a published date.)

Most of the inline documentation is drawn directly from the JSON Activity Streams 1.0 specification, with minor modifications to refer to the corresponding data types in this module and to clarify certain aspects.

Documentation

type Lens' a b = forall f. Functor f => (b -> f b) -> a -> f a

Object

data Object

Within the specification, an Object is a thing, real or imaginary, which participates in an activity. It may be the entity performing the activity, or the entity on which the activity was performed. An object consists of properties defined below. Certain object types may further refine the meaning of these properties, or they may define additional properties.

To maintain this flexibility in the Haskell environment, an Object is an opaque wrapper over an underlying JSON value, and the oRest accessor can be used to access that underlying value.

Instances

Eq Object

Show Object

ToJSON Object

FromJSON Object

emptyObject :: Object

Create an Object with no fields.

Object Lenses

oAttachments :: Lens' Object (Maybe [Object])

A collection of one or more additional, associated objects, similar to the concept of attached files in an email message. An object MAY have an attachments property whose value is a JSON Array of Objects.

oAuthor :: Lens' Object (Maybe Object)

Describes the entity that created or authored the object. An object MAY contain a single author property whose value is an Object of any type. Note that the author field identifies the entity that created the object and does not necessarily identify the entity that published the object. For instance, it may be the case that an object created by one person is posted and published to a system by an entirely different entity.

oContent :: Lens' Object (Maybe Text)

Natural-language description of the object encoded as a single JSON String containing HTML markup. Visual elements such as thumbnail images MAY be included. An object MAY contain a content property.

oDisplayName :: Lens' Object (Maybe Text)

A natural-language, human-readable and plain-text name for the object. HTML markup MUST NOT be included. An object MAY contain a displayName property. If the object does not specify an objectType property, the object SHOULD specify a displayName.

oDownstreamDuplicates :: Lens' Object (Maybe [Text])

A JSON Array of one or more absolute IRI's [RFC3987] identifying objects that duplicate this object's content. An object SHOULD contain a downstreamDuplicates property when there are known objects, possibly in a different system, that duplicate the content in this object. This MAY be used as a hint for consumers to use when resolving duplicates between objects received from different sources.

oId :: Lens' Object (Maybe Text)

Provides a permanent, universally unique identifier for the object in the form of an absolute IRI [RFC3987]. An object SHOULD contain a single id property. If an object does not contain an id property, consumers MAY use the value of the url property as a less-reliable, non-unique identifier.

oImage :: Lens' Object (Maybe MediaLink)

Description of a resource providing a visual representation of the object, intended for human consumption. An object MAY contain an image property whose value is a MediaLink.

oObjectType :: (FromJSON o, ToJSON o) => Lens' Object (Maybe o)

Identifies the type of object. An object MAY contain an objectType property whose value is a JSON String that is non-empty and matches either the "isegment-nz-nc" or the "IRI" production in [RFC3987]. Note that the use of a relative reference other than a simple name is not allowed. If no objectType property is contained, the object has no specific type.

oPublished :: Lens' Object (Maybe UTCTime)

The date and time at which the object was published. An object MAY contain a published property.

oSummary :: Lens' Object (Maybe Text)

Natural-language summarization of the object encoded as a single JSON String containing HTML markup. Visual elements such as thumbnail images MAY be included. An activity MAY contain a summary property.

oUpdated :: Lens' Object (Maybe UTCTime)

The date and time at which a previously published object has been modified. An Object MAY contain an updated property.

oUpstreamDuplicates :: Lens' Object (Maybe [Text])

A JSON Array of one or more absolute IRI's [RFC3987] identifying objects that duplicate this object's content. An object SHOULD contain an upstreamDuplicates property when a publisher is knowingly duplicating with a new ID the content from another object. This MAY be used as a hint for consumers to use when resolving duplicates between objects received from different sources.

oURL :: Lens' Object (Maybe Text)

An IRI [RFC3987] identifying a resource providing an HTML representation of the object. An object MAY contain a url property

oRest :: Lens' Object Object

Access the underlying JSON object that represents an Object

Activity

data Activity

In its simplest form, an Activity consists of an actor, a verb, an object, and a target. It tells the story of a person performing an action on or with an object -- "Geraldine posted a photo to her album" or "John shared a video". In most cases these components will be explicit, but they may also be implied.

Instances

Eq Activity

Show Activity

ToJSON Activity

FromJSON Activity

makeActivity :: Object -> UTCTime -> Activity

Create an Activity with an actor, published, and provider property.

asObject :: Activity -> Object

JSON Activity Streams 1.0 specificies that an Activity may be used as an Object. In such a case, the object may have fields permitted on either an Activity or an Object

Activity Lenses

acActor :: Lens' Activity Object

Describes the entity that performed the activity. An activity MUST contain one actor property whose value is a single Object.

acContent :: Lens' Activity (Maybe Text)

Natural-language description of the activity encoded as a single JSON String containing HTML markup. Visual elements such as thumbnail images MAY be included. An activity MAY contain a content property.

acGenerator :: Lens' Activity (Maybe Object)

Describes the application that generated the activity. An activity MAY contain a generator property whose value is a single Object.

acIcon :: Lens' Activity (Maybe MediaLink)

Description of a resource providing a visual representation of the object, intended for human consumption. The image SHOULD have an aspect ratio of one (horizontal) to one (vertical) and SHOULD be suitable for presentation at a small size. An activity MAY have an icon property.

acId :: Lens' Activity (Maybe Text)

Provides a permanent, universally unique identifier for the activity in the form of an absolute IRI [RFC3987]. An activity SHOULD contain a single id property. If an activity does not contain an id property, consumers MAY use the value of the url property as a less-reliable, non-unique identifier.

acObject :: Lens' Activity (Maybe Object)

Describes the primary object of the activity. For instance, in the activity, "John saved a movie to his wishlist", the object of the activity is "movie". An activity SHOULD contain an object property whose value is a single Object. If the object property is not contained, the primary object of the activity MAY be implied by context.

acPublished :: Lens' Activity UTCTime

The date and time at which the activity was published. An activity MUST contain a published property.

acProvider :: Lens' Activity (Maybe Object)

Describes the application that published the activity. Note that this is not necessarily the same entity that generated the activity. An activity MAY contain a provider property whose value is a single Object.

acTarget :: Lens' Activity (Maybe Object)

Describes the target of the activity. The precise meaning of the activity's target is dependent on the activities verb, but will often be the object the English preposition "to". For instance, in the activity, "John saved a movie to his wishlist", the target of the activity is "wishlist". The activity target MUST NOT be used to identity an indirect object that is not a target of the activity. An activity MAY contain a target property whose value is a single Object.

acTitle :: Lens' Activity (Maybe Text)

Natural-language title or headline for the activity encoded as a single JSON String containing HTML markup. An activity MAY contain a title property.

acUpdated :: Lens' Activity (Maybe UTCTime)

The date and time at which a previously published activity has been modified. An Activity MAY contain an updated property.

acURL :: Lens' Activity (Maybe Text)

An IRI RFC3987 identifying a resource providing an HTML representation of the activity. An activity MAY contain a url property.

acVerb :: (FromJSON v, ToJSON v) => Lens' Activity (Maybe v)

Identifies the action that the activity describes. An activity SHOULD contain a verb property whose value is a JSON String that is non-empty and matches either the "isegment-nz-nc" or the "IRI" production in [RFC3987]. Note that the use of a relative reference other than a simple name is not allowed. If the verb is not specified, or if the value is null, the verb is assumed to be "post".

acRest :: Lens' Activity Object

Access the underlying JSON object that represents an Activity

MediaLink

data MediaLink

Some types of objects may have an alternative visual representation in the form of an image, video or embedded HTML fragments. A MediaLink represents a hyperlink to such resources.

Instances

Eq MediaLink

Show MediaLink

ToJSON MediaLink

FromJSON MediaLink

makeMediaLink :: Text -> MediaLink

Create a MediaLink with just a url property, and all other properties undefined.

MediaLink Lenses

mlDuration :: Lens' MediaLink (Maybe Int)

A hint to the consumer about the length, in seconds, of the media resource identified by the url property. A media link MAY contain a "duration" property when the target resource is a time-based media item such as an audio or video.

mlHeight :: Lens' MediaLink (Maybe Int)

A hint to the consumer about the height, in pixels, of the media resource identified by the url property. A media link MAY contain a height property when the target resource is a visual media item such as an image, video or embeddable HTML page.

mlWidth :: Lens' MediaLink (Maybe Int)

A hint to the consumer about the width, in pixels, of the media resource identified by the url property. A media link MAY contain a width property when the target resource is a visual media item such as an image, video or embeddable HTML page.

mlURL :: Lens' MediaLink Text

The IRI of the media resource being linked. A media link MUST have a url property.

mlRest :: Lens' MediaLink Object

Access the underlying JSON object that represents a Media Link

Collection

data Collection

A "collection" is a generic list of Objects of any object type. The objectType of each item in the collection MAY be omitted if the type of object can be established through context. The collection is used primarily as the root of an Activity Streams document as described in Section 4, but can be used as the value of extension properties in a variety of situations.

Instances

Eq Collection

Show Collection

ToJSON Collection

FromJSON Collection

makeCollection :: [Object] -> Text -> Collection

Create a Collection with an items and a url property and fill in the corresponding totalItems field with the length of the items array.

Collection Lenses

cTotalItems :: Lens' Collection (Maybe Int)

Non-negative integer specifying the total number of activities within the stream. The Stream serialization MAY contain a totalItems property. (NOTE: there is a typo in the original specification, in which it inconsistently refers to this as either totalItems or count.)

cItems :: Lens' Collection (Maybe [Object])

An array containing a listing of Objects of any object type. If used in combination with the url property, the items array can be used to provide a subset of the objects that may be found in the resource identified by the url.

cURL :: Lens' Collection (Maybe Text)

An IRI [RFC3987] referencing a JSON document containing the full listing of objects in the collection.

cRest :: Lens' Collection Object

Access the underlying JSON object that represents a Collection