PerformerController

struct PerformerController : APIRouteCollection

The collection of /api/v3/performer/* route endpoints and handler functions related to the official performers and shadow event organizers..

Show on GitHub

PerformerLinksData
See more
Declaration
Swift

struct PerformerLinksData
Show on GitHub
registerRoutes(_:)
Required. Registers routes to the incoming router.
Declaration
Swift

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

Getting Performer Data

getOfficialPerformers(_:) Asynchronous
GET /api/v3/performer/official

Gets the list of official performers. Should match what’s on jococruise.com and on Sched.com when deployed; for the rest of the year, data should be loaded that matches the schedule data. That is, we move to next year’s performers when next year’s schedule comes out, even though performer info is iusually released long before the schedule.

URL Query Parameters:
- ?search=STRING - Full-text search across name, organization, title, and bio.
- ?start=INT - Offset from start of results set
- ?limit=INT - the maximum number of games to retrieve: 1-200, default is 50.
Declaration
Swift

func getOfficialPerformers(_ req: Request) async throws -> PerformerResponseData
Show on GitHub
getShadowPerformers(_:) Asynchronous
GET /api/v3/performer/shadow

Gets the list of shadow event organizers. We haven’t been told that we need to keep the official performer list separate from the shadow performers list, but if someone puts them in the same list it in their UI, we probably will get told to separate them.

Currently shadow cruise organizers can fill in their Performer form themselves during pre-registration (before cruise embarks, after shadow events are put on the schedule). The form doesn’t include years attended or social media links; those fields will be empty.

URL Query Parameters:
- ?search=STRING - Full-text search across name, organization, title, and bio.
- ?start=INT - Offset from start of results set
- ?limit=INT - the maximum number of games to retrieve: 1-200, default is 50.
Declaration
Swift

func getShadowPerformers(_ req: Request) async throws -> PerformerResponseData
Show on GitHub
getSelfPerformer(_:) Asynchronous
GET /api/v3/performer/self

Returns the Performer data for the current user. Only Shadow Event organizers have their Performer data associated with their Twitarr user.
Declaration
Swift

func getSelfPerformer(_ req: Request) async throws -> PerformerData
Show on GitHub
getPerformer(_:) Asynchronous
GET /api/v3/performer/:performer_id

Returns the Performer data for the given performer ID. Performer ID is separate from userID,
Declaration
Swift

func getPerformer(_ req: Request) async throws -> PerformerData
Show on GitHub

Modifying Performer Data


                    
                    
                    addSelfPerformerForEvent(_:)

Asynchronous

POST /api/v3/performer/forevent/:event_id

Creates or updates a Performer profile for the current user, associating them with the given event if they’re not already associated with it. This method is only for shadow events, but can be called by any verified user. Each user may only have one Performer associated with it, so if this user already has a Perfomer profile the new data updates it.

When associating a shadow event organizer a new event, callers should take care to call /api/v3/performer/self to check if this user has a profile already and if so, return their existing Performer fields–unless the user wants to edit them.

Does not currently use the eventUIDs'array in PerformerUploadData. This method could be modified to use this field, allowing multiple events to be set for a performer at once.

Declaration

Swift

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

Parameters

`eventID`	in URL path
`PerformerUploadData`	JSON POST content.

Return Value

HTTP status.

Show on GitHub


                    
                    
                    upsertSelfPerformer(_:)

Asynchronous

POST /api/v3/performer/self

Creates or updates the current user’s Performer profile without attaching it to any event. Only available to users with the performerselfeditor role, and to TwitarrTeam and above. The profile can later be attached to an event by TwitarrTeam, or by the user via /api/v3/performer/forevent/:event_ID for Shadow and Workshop events.

Declaration

Swift

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

Parameters


                                PerformerUploadData

JSON POST content.

Return Value

HTTP status.

Show on GitHub

saveSelfPerformer(_:eventID:for:on:) Asynchronous
Creates or updates the Performer for the given user, attaching it to the event if one is given.
Declaration
Swift

func saveSelfPerformer(_ uploadData: PerformerUploadData, eventID: UUID?, for cacheUser: UserCacheData, on req: Request) async throws
Show on GitHub
deleteSelfPerformer(_:) Asynchronous
POST /api/v3/performer/self/delete DELETE /api/v3/performer/self/performer

Deletes a shadow event organizer’s Performer record and any of their EventPerformer records (linking their Performer to their Events). We haven’t created a way to delete individual EventPerformer pivots. If a user signs up as an organizer of an event they’re not organizing (wrong event, or a non-organizer didn’t know what they were doing, or a troll), just have them delete the Performer (which also deletes all the pivots) and recreate it if necessary, attaching it to the right event(s).
Declaration
Swift

func deleteSelfPerformer(_ req: Request) async throws -> HTTPStatus
Show on GitHub

TwitarrTeam methods


                    
                    
                    upsertPerformer(_:)

Asynchronous

POST /api/v3/admin/performer/upsert

Creates or updates a Performer profile. This method may create official Performer models, and may edit Official or Shadow performers. This method does not associate the performer with any events.

The idea behind this method is that we’ll be using a bulk import method to associate events with performers, but may not end up using bulk import for performers.

Declaration

Swift

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

Parameters


                                PerformerUploadData

JSON POST content.

Return Value

HTTP status.

Show on GitHub

uploadPerformerLinkSpreadsheet(_:) Asynchronous
GET /api/v3/performer/link/upload

Uploads a Excel spreadsheet containing a list of events and which performers (by name) that will be performing at each event.
Declaration
Swift

func uploadPerformerLinkSpreadsheet(_ req: Request) async throws -> HTTPStatus
Return Value

EventPerformerValidationData

Show on GitHub
performerLinkVerificationHandler(_:) Asynchronous
GET /api/v3/performer/link/verify

Parses the Excel file uploaded in uploadPerformerLinkSpreadsheet(), matches events listed in the spreadsheet to database Events, matches performer names in the spread sheet to Performers in the db.

This method doesn’t modify the db, it just does all the matching and reports any errors.
Declaration
Swift

func performerLinkVerificationHandler(_ req: Request) async throws -> EventPerformerValidationData
Return Value

EventPerformerValidationData

Show on GitHub
performerLinkApplyHandler(_:) Asynchronous
GET /api/v3/performer/link/apply

Parses the Excel file uploaded in uploadPerformerLinkSpreadsheet(), matches events listed in the spreadsheet to database Events, matches performer names in the spread sheet to Performers in the db, creates EventPerformer pivots linking Events and their Performers.

This method deletes all existing EventPerformer pivots for official performers before saving the new ones; the assumption is that the Excel spreadsheet is the new definitive (and complete) source for which performers are at which events. Pivots that were linked manually (manuallyLinked == true) are not deleted, and a spreadsheet row that duplicates a manual link is ignored.
Declaration
Swift

func performerLinkApplyHandler(_ req: Request) async throws -> HTTPStatus
Return Value

HTTP status.

Show on GitHub
replaceOfficialPerformerPivots(with:on:) Asynchronous
Replaces the non-manual EventPerformer pivots for official performers with the given pivots. Manually linked pivots are kept, and any given pivot that duplicates a manual pivot is skipped to avoid violating the unique(performer, event) constraint.
Declaration
Swift

func replaceOfficialPerformerPivots(with newPivots: [EventPerformer], on database: Database) async throws
Show on GitHub
linkPerformerToEventHandler(_:) Asynchronous
POST /api/v3/admin/performer/:performer_ID/event/:event_ID

Links any Performer (official or shadow) to any Event. The link is marked as manual, so the spreadsheet link import won’t remove it. If the pair is already linked (for example, by the spreadsheet), the existing link is marked as manual.
Declaration
Swift

func linkPerformerToEventHandler(_ req: Request) async throws -> HTTPStatus
Return Value

.created if a new link was made, .ok if the link already existed.

Show on GitHub
unlinkPerformerFromEventHandler(_:) Asynchronous
DELETE /api/v3/admin/performer/:performer_ID/event/:event_ID

Removes the link between a Performer and an Event, whether it was made manually or by import.
Declaration
Swift

func unlinkPerformerFromEventHandler(_ req: Request) async throws -> HTTPStatus
Return Value

.ok if a link was removed, .noContent if there was no such link.

Show on GitHub

Bulk Performer Import

bulkPerformerUploadHandler(_:) Asynchronous
POST /api/v3/admin/performer/bulk/upload

Receives a JSON array of PerformerData objects (scraped from a performer listing page) and saves them to disk for later verification and application. Only one bulk import file can be “in the hopper” at a time.
Declaration
Swift

func bulkPerformerUploadHandler(_ req: Request) async throws -> HTTPStatus
Return Value

HTTP status.

Show on GitHub
bulkPerformerVerifyHandler(_:) Asynchronous
GET /api/v3/admin/performer/bulk/verify

Reads the saved bulk performer JSON file, loads all official performers from the database, and compares them by name (case-insensitive) to produce a diff. Does not modify the database.
Declaration
Swift

func bulkPerformerVerifyHandler(_ req: Request) async throws -> PerformerUpdateDifferenceData
Return Value

PerformerUpdateDifferenceData with new, updated, unchanged, and not-in-source performers.

Show on GitHub
bulkPerformerApplyHandler(_:) Asynchronous
POST /api/v3/admin/performer/bulk/apply

Reads the saved bulk performer JSON file and applies changes to the database.
- New performers are created with their photo fetched from the scraped URL.
- Existing performers have their profile fields updated (photo is intentionally skipped to avoid image diffing).
- Optionally deletes performers not in source if processDeletes=true query param is set.
- Optionally skips updates to existing performers if processUpdates=false query param is set.
Declaration
Swift

func bulkPerformerApplyHandler(_ req: Request) async throws -> HTTPStatus
Return Value

HTTP status.

Show on GitHub


                    
                    
                    deletePerformerHandler(_:)

Asynchronous

Declaration

Swift

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

Show on GitHub

Utilities


                    
                    
                    applyPerformerSearchFilter(from:to:)

Declaration

Swift

func applyPerformerSearchFilter(from req: Request, to query: QueryBuilder<Performer>) throws

Show on GitHub

uploadedPerformerLinksPath()
Declaration
Swift

func uploadedPerformerLinksPath() throws -> URL
Show on GitHub
uploadedPerformersBulkPath()
Declaration
Swift

func uploadedPerformersBulkPath() throws -> URL
Show on GitHub


                    
                    
                    readSavedBulkPerformers(on:)

Asynchronous

Declaration

Swift

func readSavedBulkPerformers(on req: Request) async throws -> [PerformerData]

Show on GitHub


                    
                    
                    performerProfileChanges(scraped:existing:)

Declaration

Swift

func performerProfileChanges(scraped: PerformerData, existing: Performer) -> [PerformerProfileFieldChangeData]

Show on GitHub


                    
                    
                    appendPerformerProfileChange(fieldName:oldValue:newValue:to:)

Declaration

Swift

func appendPerformerProfileChange(
	fieldName: String,
	oldValue: String?,
	newValue: String?,
	to changes: inout [PerformerProfileFieldChangeData]
)

Show on GitHub


                    
                    
                    performerProfileDisplayValue(_:)

Declaration

Swift

func performerProfileDisplayValue(_ value: String?) -> String

Show on GitHub


                    
                    
                    linkScrapedEvents(_:to:dbEventsByUID:dbEventsByTitleAndStartTime:existingPivotKeys:on:)

Asynchronous

Declaration

Swift

func linkScrapedEvents(
	_ scrapedEventRefs: [ScrapedPerformerEventReferenceData],
	to performer: Performer,
	dbEventsByUID: [String: Event],
	dbEventsByTitleAndStartTime: [String: Event],
	existingPivotKeys: inout Set<String>,
	on req: Request
) async throws

Show on GitHub


                    
                    
                    previewScrapedEventLinks(_:forPerformerNamed:existingPerformerID:dbEventsByUID:dbEventsByTitleAndStartTime:existingPivotKeys:addedLinks:unmatchedEvents:previewedAddedLinks:previewedUnmatchedEvents:)

Declaration

Swift

func previewScrapedEventLinks(
	_ scrapedEventRefs: [ScrapedPerformerEventReferenceData],
	forPerformerNamed performerName: String,
	existingPerformerID: UUID?,
	dbEventsByUID: [String: Event],
	dbEventsByTitleAndStartTime: [String: Event],
	existingPivotKeys: Set<String>,
	addedLinks: inout [PerformerEventLinkPreviewData],
	unmatchedEvents: inout [PerformerEventLinkPreviewData],
	previewedAddedLinks: inout Set<String>,
	previewedUnmatchedEvents: inout Set<String>
)

Show on GitHub


                    
                    
                    resolveScrapedEvent(_:dbEventsByUID:dbEventsByTitleAndStartTime:)

Declaration

Swift

func resolveScrapedEvent(
	_ scrapedEvent: ScrapedPerformerEventReferenceData,
	dbEventsByUID: [String: Event],
	dbEventsByTitleAndStartTime: [String: Event]
) -> Event?

Show on GitHub


                    
                    
                    formatBulkPerformerEventPreviewTime(_:)

Declaration

Swift

func formatBulkPerformerEventPreviewTime(_ date: Date) -> String

Show on GitHub


                    
                    
                    eventLookupKey(title:startTime:)

Declaration

Swift

func eventLookupKey(title: String, startTime: Date) -> String

Show on GitHub


                    
                    
                    eventPerformerLookupKey(performerID:eventID:)

Declaration

Swift

func eventPerformerLookupKey(performerID: UUID, eventID: UUID) -> String

Show on GitHub


                    
                    
                    eventPerformerLookupKey(performerID:eventID:)

Declaration

Swift

func eventPerformerLookupKey(performerID: UUID, eventID: UUID?) -> String

Show on GitHub


                    
                    
                    findPerformerLinkEventMatch(for:in:)

Declaration

Swift

func findPerformerLinkEventMatch(for importedEvent: PerformerLinksData, in dbEvents: [Event]) -> Event?

Show on GitHub


                    
                    
                    normalizedPerformerLinkEventTitle(_:)

Declaration

Swift

func normalizedPerformerLinkEventTitle(_ title: String) -> String

Show on GitHub


                    
                    
                    performerLinkComparableEventTitle(_:)

Declaration

Swift

func performerLinkComparableEventTitle(_ title: String) -> String

Show on GitHub


                    
                    
                    getFavorites(in:from:)

Asynchronous

Declaration

Swift

func getFavorites(in req: Request, from events: [Event]? = nil) async throws -> Set<UUID>

Show on GitHub


                    
                    
                    buildPerformerFromUploadData(performer:uploadData:on:)

Asynchronous

Declaration

Swift

func buildPerformerFromUploadData(performer: inout Performer, uploadData: PerformerUploadData, on req: Request) async throws

Show on GitHub


                    
                    
                    parsePerformerLinksTextFile(from:)

Declaration

Swift

func parsePerformerLinksTextFile(from fileData: Data) throws -> ([PerformerLinksData], [String])

Show on GitHub


                    
                    
                    parsePerformerLinksExcelDoc(from:)

Declaration

Swift

func parsePerformerLinksExcelDoc(from fileData: Data) throws -> ([PerformerLinksData], [String])

Show on GitHub


                    
                    
                    weekdayAndTimeToDate(weekday:startTime:)

Declaration

Swift

func weekdayAndTimeToDate(weekday day: String, startTime: String) throws -> Date

Show on GitHub


                    
                    
                    findExcelHeaderColumn(named:in:sharedStrings:defaultValue:errors:)

Declaration

Swift

func findExcelHeaderColumn(named: String, in row: Row, sharedStrings: SharedStrings, defaultValue: String, errors: inout [String]) -> ColumnReference

Show on GitHub


                    
                    
                    cellValue(in:col:sharedStrings:)

Declaration

Swift

func cellValue(in row: Row, col: ColumnReference, sharedStrings: SharedStrings) -> String?

Show on GitHub