From dd75cf32a58d270225804415dea837d21d41a7d4 Mon Sep 17 00:00:00 2001 From: Tristan Barlow Date: Tue, 17 Sep 2024 15:29:45 +0100 Subject: [PATCH] Verification Job - Annotated types --- docs/verification/Verification.md | 11 +++ packages/lvs-types/src/v1/verificationJob.ts | 79 +++++++++++++++++--- 2 files changed, 79 insertions(+), 11 deletions(-) diff --git a/docs/verification/Verification.md b/docs/verification/Verification.md index b74ac52..005a222 100644 --- a/docs/verification/Verification.md +++ b/docs/verification/Verification.md @@ -58,3 +58,14 @@ The resulting file name would be: `Open_US_Tigers.mp3` ### *WARNING!* Do not add the file extension on the end of the file name, the correct file extension will be applied automatically. + +## Webhooks +To set up webhooks for an organisation go to the [my organisation's page](https://verification.clicknclear.com/en-gb/my/orgs), select the organisation you want to edit and then go to the webhooks tab. + +### *All webhook URLs are invoked via a POST request!* + +When setting the URL for the webhook you should add security to the URL, for example you could use a query parameter: https://none.clicknclear.com/webhook?key=23456789. + +Feel free to rotate URLs as much as you like, you can also have multiple webhooks for the same event. + +There is also a 'Test' button, which will call the webhook with a test payload. The payload sent to the webhook will be test data so should be ignored when received. diff --git a/packages/lvs-types/src/v1/verificationJob.ts b/packages/lvs-types/src/v1/verificationJob.ts index 0ff4c98..cf82110 100644 --- a/packages/lvs-types/src/v1/verificationJob.ts +++ b/packages/lvs-types/src/v1/verificationJob.ts @@ -4,61 +4,118 @@ import { ISoundRecordingVerificationV1 } from './soundRecording'; import { LicenseSourceV1 } from './license'; export enum VerificationJobStatusV1 { - //Uploaded + //The initial status given to the verification job Created = 'Created', - //Queued for matching + //The audio file is being downloaded and converted Downloading = 'Downloading', - //Matching + //The audio file currently being put through automatic song detection Matching = 'Matching', - //Finished + //The automatic matching has been completed, the license data will start downloading Matched = 'Matched', - //ClicknClear has finished processing + //All automatic processes have been completed Completed = 'Completed', - //User has confirmed matches + //The end user has confirmed the detected songs are correct Confirmed = 'Confirmed', - //Something has gone wrong - Errored = 'Errored', + //Something has gone wrong, see the error message for more details + Errored = 'Errored' } export type VerificationJobLicenseDetailsV1 = z.infer export const verificationJobLicenseDetailsV1 = z.object({ + //The type of license that is being uploaded. + //For 'ClicknClear' and 'Pending License' do not supply any license details. + //ClicknClear licenses are fetched automatically based on the users email address licenseSource: z.nativeEnum(LicenseSourceV1), + //The name of the license source eg 'Other Platform' licenseSourceName: z.string(), - licenseFileURLs: z.string().array() + //A list of URLs to download any of the relevant license files + licenseFileURLs: z.string().url().array() }); export const verificationJobTagSchemaV1 = z.string().min(2).max(255); +/** + * Used in the Create Verification Job Endpoint to create a verification job + */ export type VerificationJobCreateV1 = z.infer export const verificationJobCreateSchemaV1 = z.object({ + //The name of the Team/Athlete/Licensee name: z.string(), + //The email address attached to any licenses the Team/Athlete/Licensee might have email: z.string().email(), + //The territories required by organisation, for example the territories the event is happening in. ["US", "GB"] requiredTerritories: z.string().length(2).array(), + //The start date used when checking if licenses are valid startDate: zParsedDate(), + //The end date used when checking if licenses are valid endDate: zParsedDate(), + //The external identifiers you have, for example your own Team/Athlete Id externalId: z.string().nullable(), + //The organisationId this job should be created under. To find your organisation Ids please refer to the "Get My Organisations" request in the postman documentation. organisationId: z.number(), - audioFileURL: z.string(), + //The URL to download the audio/video file + audioFileURL: z.string().url(), + //An array of tags which can be used to search or categorise the verification job tags: verificationJobTagSchemaV1.array(), + //Any licensing information the Team/Athlete/Licensee can provide, for ClicknClear licenses or if they don't have any license please leave empty. licenseDetails: verificationJobLicenseDetailsV1.array() }); export interface IVerificationJobV1 { id: number + /** + * Name of the Team/Athlete/Licensee + */ name: string + /** + * The email address attached to any licenses the Team/Athlete/Licensee might have + */ email: string + /** + * The territories required by organisation, for example the territories the event is happening in. ["US", "GB"] + */ requiredTerritories: string[] + /** + * ISODate string - The start date used when checking if licenses are valid + */ startDate: string + /** + * ISODate string - The end date used when checking if licenses are valid + */ endDate: string + /** + * The external identifiers you have, for example your own Team/Athlete Id + */ externalId: string | null + /** + * The Organisation Id that the verification job belongs to + */ organisationId: number - soundRecordingId: number | null + /** + * The current status of the verification job + */ status: VerificationJobStatusV1 + /** + * A string containing any messages from any errors that might have occurred. An empty string signifies no message + */ errorMessage: string + /** + * An array of the tags provided when the job was created + */ tags: string[] + /** + * The ID of the sound recording created from the audioFileURL + */ + soundRecordingId: number | null + /** + * The recording that was downloaded from audioFileURL, all songs and license status are contained within this property. + */ recording: ISoundRecordingVerificationV1 | null } +/** + * The payload of the 'Verification Job - Status Update' event + */ export interface IVerificationJobStatusUpdateV1 { id: number status: VerificationJobStatusV1