TwitarrController

struct TwitarrController : APIRouteCollection

The collection of /api/v3/twitarr/* route endpoint and handler functions related to the twit-arr stream.

Show on GitHub

RouteCollection Conformance

registerRoutes(_:)
Empty stub register fn; Twarrt stream has been decomissioned.
Declaration
Swift

func registerRoutes(_ app: Application) throws
Show on GitHub
DISABLED_registerRoutes(_:)
Required. Registers routes to the incoming router.
Declaration
Swift

func DISABLED_registerRoutes(_ app: Application) throws
Show on GitHub

tokenAuthGroup Handlers (logged in)


                    
                    
                    twarrtHandler(_:)

Asynchronous

GET /api/v3/twitarr/ID

Retrieve the specified Twarrt with full user LikeType data.

Throws

404 error if the twarrt is not available.

Declaration

Swift

func twarrtHandler(_ req: Request) async throws -> TwarrtDetailData

Parameters


                                twarrtID

in URL path

Return Value

TwarrtDetailData containing the specified twarrt.

Show on GitHub

twarrtsHandler(_:) Asynchronous
GET /api/v3/twitarr

Retrieve an array of Twarrts. This query supports several optional query parameters.

URL Query Parameters

Parameters that filter the set of returned Twarrts. These may be combined (but only one instance of each); the result set will match all provided filters.
- ?search=STRING - Only return twarrts whose text contains the search string.
- ?hashtag=STRING - Only return twarrts whose text contains the given #hashtag. The # is not required in the value.
- ?mentions=STRING - Only return twarrts that @mention the given username. The @ is not required in the value.
- ?mentionSelf=true - Matches posts whose text contains a @mention of the current user.
- ?byUser=ID - Only return twarrts authored by the given user.
- ?byUsername=STRING - Only return twarrts authored by the given user.
- ?bookmarked=true - Only return twarrts the user has bookmarked.
- ?replyGroup=ID - Only return twarrts in the given replyGroup. The twarrt whose twarrtID == ID is always considered to be in the reply group, even if there are no replies to it.
- ?hideReplies=true - Filter out twarrts that are replies to other twarrts. Will still return the twarrt that starts a replyGroup. Ignored if replyGroup option is used.
- ?likeType=[like, laugh, love, all] - Only return twarrts the user has reacted to.
Parameters that set the anchor. The anchor can be a specific Twarrt, a Date, or the first or last twarrt in the stream. These parameters are mutually exclusive. The default anchor if none is specified is ?from=last. If you specify a twarrt ID as an anchor, that twarrt does not need to pass the filter params (see above).
- ?after=ID - the ID of the twarrt after which the retrieval should start (newer).
- ?before=ID - the ID of the twarrt before which the retrieval should start (older).
- ?afterDate=DATE - the timestamp after which the retrieval should start (newer).
- ?beforeDate=DATE - the timestamp before which the retrieval should start (older).
- ?from=STRING - retrieve starting from “first” or “last”.
These parameters operate on the filtered set of twarrts, starting at the anchor, above. These parameters can be used to implement paging that is invariant to new results being added while displaying filtered twarrts. That is, for an initial call with ?hashtag=joco&from=last, on subsequent calls you can call ?hashtag=joco&before=<id of first result>&start=50 and you will get the 50 twarrts containing the #joco hashtag, occuring immediately before the 50 results returned in the first call– even if there have been more twarrts posted with the hashtag in the interim.
- ?start=INT - the offset from the anchor to start. Offset only counts twarrts that pass the filters.
- ?limit=INT - the maximum number of twarrts to retrieve: 1-200, default is 50
A query without additional parameters defaults to ?limit=50&from=last, the 50 most recent twarrts.

DATE values can be either TimeInterval values (Doubles) since epoch, or ISO8601 string representations including milliseconds (“yyyy-MM-dd’T'HH:mm:ss.SSSXXXXX”). The numeric value method is recommended.

Note

It is highly recommended that clients use after=ID or before=ID where possible. Twarrt ID’s are Int values and thus unambiguous. DATE values are accurate only within 1 millisecond and are therefore prone to rounding errors. To ensure that all twarrts of interest are returned when sending a date based on the value found in a twarrt’s timestamp, it is recommended that 1 millisecond be added (if retrieving older) or subtracted (if retrieving newer) from that value for the query. You will almost certainly receive the original anchor twarrt again, but it will also ensure that any others possibly created within the same millisecond will not be omitted.

Note

Blocks are always applied to the search results. User mutes are applied to the search results unless a filter is used that involves users or twarrts the user has previously interacted with (inBarrel, likeType, bookmarked) or matches users by name (byuser).

Throws

400 error if a date parameter was supplied and is in an unknown format.
Declaration
Swift

func twarrtsHandler(_ req: Request) async throws -> [TwarrtData]
Return Value

An array of TwarrtData containing the requested twarrts.

Show on GitHub


                    
                    
                    bookmarkAddHandler(_:)

Asynchronous

POST /api/v3/twitarr/ID/bookmark

Add a bookmark of the specified Twarrt.

Throws

400 error if the twarrt is already bookmarked.

Declaration

Swift

func bookmarkAddHandler(_ req: Request) async throws -> HTTPStatus

Parameters


                                twarrtID

in URL path

Return Value

201 Created on success.

Show on GitHub


                    
                    
                    bookmarkRemoveHandler(_:)

Asynchronous

POST /api/v3/twitarr/ID/bookmark/remove

Remove a bookmark of the specified Twarrt.

Throws

400 error if the user has not bookmarked any twarrts.

Declaration

Swift

func bookmarkRemoveHandler(_ req: Request) async throws -> HTTPStatus

Parameters


                                twarrtID

in URL path

Return Value

204 NoContent on success.

Show on GitHub


                    
                    
                    replyHandler(_:)

Asynchronous

POST /api/v3/twitarr/:twarrt_ID/reply

Create a Twarrt as a reply to an existing twarrt. If the replyTo twarrt is in quarantine, the post is rejected.

Note

Replies work differently than on Twitter. Here, any twarrt that is replied to becomes a reply-group, and all twarrts replying to ANY twarrt in the reply-group are added to that reply-group. Reply-groups are not nestable, and every twarrt is a member of at most one reply group. Twarrts that are not replies themselves are eligible to become the head of a reply-group if they are replied to. Twarrts that are replies are placed in a reply-group whose ID is the twarrt ID of the first twarrt in the group. This may not be the ID of the twarrt they’re directly replying to. If B is created as a reply to A, and C is created as a reply to B, C is actually placed in a reply-group with both A and B.

One feature of this system for replies is that TwarrtData.replyGroupID can be used to discern whether a twarrt is part of a reply-group or not.

Throws

400 error if the replyTo twarrt is in quarantine.

Declaration

Swift

func replyHandler(_ req: Request) async throws -> Response

Parameters

`twarrtID`	in URL path. The twarrt to reply to.
`requestBody`	`PostContentData`

Return Value

A TwarrtData containing the twarrt’s contents and metadata. HTTP 201 status if successful.

Show on GitHub


                    
                    
                    twarrtCreateHandler(_:)

Asynchronous

POST /api/v3/twitarr/create

Create a new Twarrt in the twitarr stream.

Declaration

Swift

func twarrtCreateHandler(_ req: Request) async throws -> Response

Parameters


                                requestBody

PostContentData

Return Value

TwarrtData containing the twarrt’s contents and metadata. HTTP 201 status if successful.

Show on GitHub


                    
                    
                    twarrtDeleteHandler(_:)

Asynchronous

POST /api/v3/twitarr/ID/delete DELETE /api/v3/twitarr/ID

Delete the specified Twarrt.

Throws

403 error if the user is not permitted to delete.

Declaration

Swift

func twarrtDeleteHandler(_ req: Request) async throws -> HTTPStatus

Parameters


                                twarrtID

in URL path. The twarrt to delete.

Return Value

204 No Content on success.

Show on GitHub


                    
                    
                    twarrtReportHandler(_:)

Asynchronous

POST /api/v3/twitarr/ID/report

Create a Report regarding the specified Twarrt. If the twarrt has reached the report threshold for auto-quarantining, it is quarantined.

Note

The accompanying report message is optional on the part of the submitting user, but the ReportData is mandatory in order to allow one. If there is no message, sent an empty string in the .message field.

Throws

400 error if user has already submitted report.

Declaration

Swift

func twarrtReportHandler(_ req: Request) async throws -> HTTPStatus

Parameters

`twarrtID`	in URL path. The twarrt to report.
`requestBody`	`ReportData`

Return Value

201 Created on success.

Show on GitHub


                    
                    
                    twarrtLaughHandler(_:)

Asynchronous

POST /api/v3/twitarr/ID/laugh

Add a “laugh” reaction to the specified Twarrt. If there is an existing LikeType reaction by the user, it is replaced.

Throws

403 error if user is the twarrt’s creator.

Declaration

Swift

func twarrtLaughHandler(_ req: Request) async throws -> TwarrtData

Parameters


                                twarrtID

in URL path.

Return Value

TwarrtData containing the updated like info.

Show on GitHub


                    
                    
                    twarrtLikeHandler(_:)

Asynchronous

POST /api/v3/twitarr/ID/like

Add a “like” reaction to the specified Twarrt. If there is an existing LikeType reaction by the user, it is replaced.

Throws

403 error if user is the twarrt’s creator.

Declaration

Swift

func twarrtLikeHandler(_ req: Request) async throws -> TwarrtData

Parameters


                                twarrtID

in URL path.

Return Value

TwarrtData containing the updated like info.

Show on GitHub


                    
                    
                    twarrtLoveHandler(_:)

Asynchronous

POST /api/v3/twitarr/ID/love

Add a “love” reaction to the specified Twarrt. If there is an existing LikeType reaction by the user, it is replaced.

Throws

403 error if user is the twarrt’s creator.

Declaration

Swift

func twarrtLoveHandler(_ req: Request) async throws -> TwarrtData

Parameters


                                twarrtID

in URL path.

Return Value

TwarrtData containing the updated like info.

Show on GitHub


                    
                    
                    twarrtReactHandler(_:likeType:)

Asynchronous

Add a reaction to the specified Twarrt. If there is an existing LikeType reaction by the user, it is replaced. All 3 reaction handlers use this function as they all do the same thing.

Throws

403 error if user is the twarrt’s creator.

Declaration

Swift

func twarrtReactHandler(_ req: Request, likeType: LikeType) async throws -> TwarrtData

Parameters

`req`	The incoming `Request`, provided automatically.
`likeType`	The type of reaction being set.

Return Value

TwarrtData containing the updated like info.

Show on GitHub


                    
                    
                    twarrtUnreactHandler(_:)

Asynchronous

POST /api/v3/twitarr/ID/unreact DELETE /api/v3/twitarr/ID/reaction

Remove a LikeType reaction from the specified Twarrt.

Throws

403 error if user is is the twarrt’s creator. 404 if no twarrt with the ID is found.

Declaration

Swift

func twarrtUnreactHandler(_ req: Request) async throws -> TwarrtData

Parameters


                                twarrtID

in URL path.

Return Value

TwarrtData containing the updated like info.

Show on GitHub


                    
                    
                    twarrtUpdateHandler(_:)

Asynchronous

POST /api/v3/twitarr/ID/update

Update the specified Twarrt.

Throws

403 error if user is not twarrt owner or has read-only access.

Declaration

Swift

func twarrtUpdateHandler(_ req: Request) async throws -> TwarrtData

Parameters

`twarrtID`	in URL path.
`requestBody`	`PostContentData`

Return Value

TwarrtData containing the twarrt’s contents and metadata.

Show on GitHub


                    
                    
                    buildTwarrtData(from:userID:on:)

Asynchronous

Declaration

Swift

func buildTwarrtData(from twarrt: Twarrt, userID: UUID, on req: Request) async throws -> TwarrtData

Show on GitHub


                    
                    
                    buildTwarrtData(from:userID:on:mutewords:assumeBookmarked:matchHashtag:)

Asynchronous

Declaration

Swift

func buildTwarrtData(
	from twarrts: [Twarrt],
	userID: UUID,
	on req: Request,
	mutewords: [String]? = nil,
	assumeBookmarked: Bool? = nil,
	matchHashtag: String? = nil
) async throws -> [TwarrtData]

Show on GitHub


                    
                    
                    processTwarrtMentions(twarrt:editedText:isCreate:on:)

Asynchronous

Declaration

Swift

func processTwarrtMentions(twarrt: Twarrt, editedText: String?, isCreate: Bool = false, on req: Request)
	async throws

Show on GitHub