@uptime.app/contracts 1.0.2 → 1.0.3

package/dist/esm/text-to-speech/text-segment.d.ts

@@ -0,0 +1,25 @@
+export interface TextSegment {
+    parentId: string;
+    textSegmentId: string;
+    content: string;
+}
+export interface TextSegmentWithSpeech extends TextSegment {
+    speech: Speech[];
+    spokenContent: string;
+}
+export interface Speech {
+    voice: Voice;
+    url: string;
+}
+export interface Voice {
+    id: string;
+    language: string;
+    name: string;
+    countryCode: string;
+    /** use SupportedSpeechProvider */
+    speechProvider: string;
+}
+export declare enum SupportedSpeechProvider {
+    MicrosoftAzure = "microsoft-azure"
+}
+//# sourceMappingURL=text-segment.d.ts.map

package/dist/esm/text-to-speech/text-segment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-segment.d.ts","sourceRoot":"","sources":["../../../src/text-to-speech/text-segment.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAsB,SAAQ,WAAW;IACtD,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,aAAa,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,MAAM;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,KAAK;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,oBAAY,uBAAuB;IAC/B,cAAc,oBAAoB;CACrC"}

package/dist/esm/text-to-speech/text-segment.js

@@ -0,0 +1,5 @@
+export var SupportedSpeechProvider;
+(function (SupportedSpeechProvider) {
+    SupportedSpeechProvider["MicrosoftAzure"] = "microsoft-azure";
+})(SupportedSpeechProvider || (SupportedSpeechProvider = {}));
+//# sourceMappingURL=text-segment.js.map

package/dist/esm/text-to-speech/text-segment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-segment.js","sourceRoot":"","sources":["../../../src/text-to-speech/text-segment.ts"],"names":[],"mappings":"AA0BA,MAAM,CAAN,IAAY,uBAEX;AAFD,WAAY,uBAAuB;IAC/B,6DAAkC,CAAA;AACtC,CAAC,EAFW,uBAAuB,KAAvB,uBAAuB,QAElC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uptime.app/contracts",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "license": "MIT",
   "types": "./dist/esm/index.d.ts",
   "main": "./dist/cjs/index.js",
@@ -13,5 +13,5 @@
   "devDependencies": {
     "typescript": "^5.4.3"
   },
-  "gitHead": "6a25fc101adc1327b31d6ea4e24aa40d33db03a5"
+  "gitHead": "0250cf2a99f7c8e575521b81defbf7e6b962ae99"
 }

package/src/hack/extracted-subject.ts

@@ -0,0 +1,5 @@
+
+// defined in @uptime.app/subject-extraction-service but trying to avoid too many dependencies
+export interface ExtractedSubject {
+    name: string;
+}

package/src/hack/hack-events.ts

@@ -0,0 +1,21 @@
+import { Hack } from './hack';
+
+export interface HackCreatedEvent {
+    id: string;
+    type: 'HackCreated';
+    payload: Hack;
+}
+
+export interface HackUpdatedEvent {
+    id: string;
+    type: 'HackUpdated';
+    payload: Hack;
+}
+
+export interface HackDeletedEvent {
+    id: string;
+    type: 'HackDeleted';
+    payload: Hack;
+}
+
+export type HackChangedEvent = HackCreatedEvent | HackUpdatedEvent | HackDeletedEvent;

package/src/hack/hack-with-voice-events.ts

@@ -0,0 +1,21 @@
+import { HackWithVoice } from './hack-with-voice';
+
+export interface HackWithVoiceCreatedEvent {
+    id: string;
+    type: 'HackWithVoiceCreated';
+    payload: HackWithVoice;
+}
+
+export interface HackWithVoiceUpdatedEvent {
+    id: string;
+    type: 'HackWithVoiceUpdated';
+    payload: HackWithVoice;
+}
+
+export interface HackWithVoiceDeletedEvent {
+    id: string;
+    type: 'HackWithVoiceDeleted';
+    payload: HackWithVoice;
+}
+
+export type HackWithVoiceChangedEvent = HackWithVoiceCreatedEvent | HackWithVoiceUpdatedEvent | HackWithVoiceDeletedEvent;

package/src/hack/hack-with-voice.ts

@@ -0,0 +1,33 @@
+import { Segment } from '../segment/segment';
+
+/**
+ * HackWithVoice contains the Hack segments a a few basic Hack fields, it does not contain other Hack information.
+ * This decision was made due to the complexity of editorialTags and updating them.
+ */
+export interface HackWithVoice {
+    /** NOT the id of the hack. Use hackId. The id cannot be the hackId as otherwise id would be duplicated for each voice which would break message replay */
+    id: string;
+    /** The id of the hack */
+    hackId: string;
+    baseLocaleHackId: string;
+    /** The id of voice used to generate the audio */
+    voiceId: string;
+    /** True if this is the default voice */
+    isDefaultVoice: boolean;
+    v: number;
+    createdAt: string;
+    updatedAt: string;
+
+    segments: {
+        favouriteQuote: Segment;
+        inANutshell: Segment;
+        introduction: Segment;
+        insights: Segment[];
+        conclusion: Segment;
+        // composite segments
+        overview: Segment;
+        shareableOverview: Segment;
+        hereAreTheInsights: Segment;
+        putInAction?: Segment;
+    }
+}

package/src/hack/hack.ts

@@ -0,0 +1,114 @@
+import { ExtractedSubject } from './extracted-subject';
+export interface Hack {
+    /** The unique id of the hack. */
+    id: string;
+    /** The locale (language and region) of the hack e.g. fr-FR. Use @uptime.app/localisation-contracts Mandatory property since 12/01/2023. */
+    locale: string;
+    /** The id of the hack in its original locale. Mandatory property since 12/01/2023. */
+    baseLocaleHackId: string;
+    v: number;
+    createdAt: string;
+    updatedAt: string;
+    owner: string;
+    sourceId?: string;
+    title: string;
+    themeId: string;
+
+    /** introduced Oct 2023 **/
+    draftHackId: string;
+    draftHackVersion: number;
+
+    // TODO I'd remove it altogether, but it would be a breaking contract change. Thoughts?
+    isHidden?: boolean;
+
+    editorialTags?: string[];
+    coverUrl?: string;
+    notifications?: {
+        aiGeneratedText?: string
+        humanCuratedText?: string;
+    },
+    segments: {
+        favouriteQuote: {
+            id: string;
+            /** added 04/2023 */
+            v?: number;
+        };
+        inANutshell: {
+            id: string;
+            /** added 04/2023 */
+            v?: number;
+        };
+        introduction: {
+            id: string;
+            /** added 04/2023 */
+            v?: number;
+        };
+        insights: {
+            id: string
+            /** added 04/2023 */
+            v?: number;
+        }[];
+        conclusion: {
+            id: string;
+            /** added 04/2023 */
+            v?: number;
+        };
+
+        // composite segments
+        overview: {
+            id: string;
+            /** added 04/2023 */
+            v?: number;
+        };
+        shareableOverview: {
+            id: string;
+            /** added 04/2023 */
+            v?: number;
+        };
+        hereAreTheInsights: {
+            id: string;
+            /** added 04/2023 */
+            v?: number;
+        };
+        putInAction?: {
+            id: string;
+            /** added 04/2023 */
+            v?: number;
+        };
+    };
+    affiliate?: HackAffiliate;
+    topics: HackTopic[];
+    contributors?: HackContributor[];
+    type: HackType;
+    sourceData?: HackSourceData;
+    externalLink?: HackExternalLink;
+
+    /** added Mar 2024 */
+    // TODO make it mandatory after a republish
+    subjects?: ExtractedSubject[];
+}
+
+export interface HackContributor {
+    name: string;
+}
+
+export interface HackTopic {
+    name: string;
+}
+
+export interface HackAffiliate {
+    url: string;
+    name: string;
+}
+
+export declare type HackType = 'book' | 'course' | 'documentary' | 'podcast' | 'original';
+
+export interface HackSourceData {
+    episodeTitle?: string;
+    releaseDate?: string;
+}
+
+export interface HackExternalLink {
+    url: string;
+    type: 'Website' | 'Book' | 'Course' | 'Podcast' | 'Video' | 'Other';
+}

package/src/index.ts

@@ -1 +1,23 @@
-export * from './hack';
+export * from './hack/extracted-subject';
+export * from './hack/hack';
+export * from './hack/hack-with-voice';
+export * from './hack/hack-events';
+export * from './hack/hack-with-voice-events';
+
+export * from './localisation/live-locales';
+export * from './localisation/locale-language';
+export * from './localisation/supported-languages';
+export * from './localisation/supported-locales';
+
+export * from './pending-hack/pending-hack';
+export * from './pending-hack/pending-hack-events';
+export * from './pending-hack/pending-hack-with-voice';
+export * from './pending-hack/pending-hack-with-voice-events';
+
+export * from './segment/segment-with-voice';
+export * from './segment/segment-commands';
+export * from './segment/segment';
+
+export * from './text-to-speech/create-speech-commands';
+export * from './text-to-speech/speech-created-events';
+export * from './text-to-speech/text-segment';

package/src/localisation/live-locales.ts

@@ -0,0 +1,33 @@
+import { DEFAULT_LOCALE, SupportedLocale } from './supported-locales';
+
+/**
+ * All locale codes that are live and in use in the app
+ */
+export function allLiveLocaleCodes(): SupportedLocale[] {
+    return [
+        SupportedLocale.enGB,
+        SupportedLocale.enUS,
+        SupportedLocale.ptBR,
+        SupportedLocale.es,
+        SupportedLocale.frFR,
+        SupportedLocale.itIT,
+        SupportedLocale.nlNL,
+        SupportedLocale.deDE,
+        SupportedLocale.frCA,
+        SupportedLocale.plPL,
+        SupportedLocale.svSE,
+        SupportedLocale.trTR
+    ];
+}
+
+export function localeCodeIsLive(localeCode: string) {
+    return allLiveLocaleCodes().includes(localeCode as SupportedLocale);
+}
+
+export function liveLocaleFrom(localeCode?: string): SupportedLocale {
+    const locale = allLiveLocaleCodes().find(liveLocale => liveLocale  == localeCode);
+    if (!locale) {
+        return DEFAULT_LOCALE;
+    }
+    return locale;
+}

package/src/localisation/locale-language.ts

@@ -0,0 +1,4 @@
+export function languageOf(locale: string): string {
+    if (!locale) return ''; // temp: defend against an undefined locale
+    return locale.split('-')[0];
+}

package/src/localisation/supported-languages.ts

@@ -0,0 +1,11 @@
+import { allSupportedLocaleCodes } from './supported-locales';
+
+export function allSupportedLanguageCodes(): string[] {
+    const languageCodes = allSupportedLocaleCodes().map(locale => locale.split('-')[0]);
+    const uniqueLanguageCodes = [...new Set(languageCodes)];
+
+    return uniqueLanguageCodes;
+}
+
+export const ENGLISH_LANGUAGE = 'en';
+export const DEFAULT_LANGUAGE = ENGLISH_LANGUAGE;

package/src/localisation/supported-locales.ts

@@ -0,0 +1,42 @@
+export enum SupportedLocale {
+    /** English (United Kingdom) */
+    enGB = 'en-GB',
+    /** English (United States) */
+    enUS = 'en-US',
+    /** Portuguese (Brazil) */
+    ptBR = 'pt-BR',
+    /** Spanish (International) */
+    es = 'es',
+    /** French (France) */
+    frFR = 'fr-FR',
+    /** Italian */
+    itIT = 'it-IT',
+    /** Dutch */
+    nlNL = 'nl-NL',
+    /** German */
+    deDE = 'de-DE',
+    /** Polish */
+    plPL = 'pl-PL',
+    /** Swedish */
+    svSE = 'sv-SE',
+    /** Turkish */
+    trTR = 'tr-TR',
+    /** Canadian French */
+    frCA = 'fr-CA',
+    /** Traditional Chinese */
+    zhTW = 'zh-TW',
+    /** Simplified Chinese */
+    zhCN = 'zh-CN',
+    /** Malaysian Malay */
+    msMY = 'ms-MY'
+
+}
+
+/**
+ * All supported locale codes. Use allLiveLocaleCodes() instead when checking for locale codes supported by the app
+ */
+export function allSupportedLocaleCodes(): string[] {
+    return Object.values(SupportedLocale);
+}
+
+export const DEFAULT_LOCALE = SupportedLocale.enUS;

package/src/pending-hack/pending-hack-events.ts

@@ -0,0 +1,21 @@
+import { PendingHack } from './pending-hack';
+
+export interface PendingHackCreatedEvent {
+    id: string;
+    type: 'PendingHackCreated';
+    payload: PendingHack;
+}
+
+export interface PendingHackUpdatedEvent {
+    id: string;
+    type: 'PendingHackUpdated';
+    payload: PendingHack;
+}
+
+export interface PendingHackDeletedEvent {
+    id: string;
+    type: 'PendingHackDeleted';
+    payload: PendingHack;
+}
+
+export type PendingHackChangedEvent = PendingHackCreatedEvent | PendingHackUpdatedEvent | PendingHackDeletedEvent;

package/src/pending-hack/pending-hack-with-voice-events.ts

@@ -0,0 +1,21 @@
+import { PendingHackWithVoice } from './pending-hack-with-voice';
+
+export interface PendingHackWithVoiceCreatedEvent {
+    id: string;
+    type: 'PendingHackWithVoiceCreated';
+    payload: PendingHackWithVoice;
+}
+
+export interface PendingHackWithVoiceUpdatedEvent {
+    id: string;
+    type: 'PendingHackWithVoiceUpdated';
+    payload: PendingHackWithVoice;
+}
+
+export interface PendingHackWithVoiceDeletedEvent {
+    id: string;
+    type: 'PendingHackWithVoiceDeleted';
+    payload: PendingHackWithVoice;
+}
+
+export type PendingHackWithVoiceChangedEvent = PendingHackWithVoiceCreatedEvent | PendingHackWithVoiceUpdatedEvent | PendingHackWithVoiceDeletedEvent;

package/src/pending-hack/pending-hack-with-voice.ts

@@ -0,0 +1,25 @@
+/* eslint-disable @typescript-eslint/ban-types */
+import { Segment } from '../segment/segment';
+import { CompletePendingHack, PendingHack } from './pending-hack';
+
+export interface PendingHackWithVoice {
+    id: string;
+    v: number;
+    createdAt: string;
+    updatedAt: string;
+    voiceId: string;
+    isDefaultVoice: boolean;
+    hackId: string;
+    baseLocaleHackId: string;
+    segments: PendingHack['segments'];
+}
+
+export interface CompletePendingHackWithVoice extends PendingHackWithVoice {
+    segments: CompletePendingHack['segments'];
+}
+
+export type CompletePendingHackWithVoiceWithPutInAction = CompletePendingHackWithVoice & {
+    segments: {
+        putInAction: Segment;
+    }
+};

package/src/pending-hack/pending-hack.ts

@@ -0,0 +1,75 @@
+/* eslint-disable @typescript-eslint/ban-types */
+import { ExtractedSubject } from '../hack/extracted-subject';
+import { HackAffiliate, HackContributor, HackType, HackSourceData, HackTopic, HackExternalLink } from '../hack/hack';
+import { Segment } from '../segment/segment';
+
+export interface PendingHack {
+    id: string;
+    /** use @uptime.app/localisation-contracts */
+    locale: string;
+    baseLocaleHackId: string;
+    v: number;
+    createdAt: string;
+    updatedAt: string;
+    owner?: string;
+    draftHackId: string;
+    draftHackVersion: number;
+    hackId: string;
+    sourceId?: string;
+    title: string;
+    themeId: string;
+    coverUrl?: string;
+    affiliate?: HackAffiliate;
+    topics: HackTopic[];
+    contributors: HackContributor[];
+    type: HackType;
+    sourceData?: HackSourceData;
+    notifications?: {
+        aiGeneratedText?: string;
+        humanCuratedText?: string;
+    };
+    segments: {
+        favouriteQuote: Segment | {};
+        inANutshell: Segment | {};
+        introduction: Segment | {};
+        insights: [
+            (Segment | {}),
+            (Segment | {}),
+            (Segment | {})
+        ];
+        conclusion: Segment | {};
+        // composite segments
+        overview: Segment | {};
+        shareableOverview: Segment | {};
+        hereAreTheInsights: Segment | {};
+        putInAction?: Segment | {};
+    };
+    externalLink?: HackExternalLink;
+    subjects?: ExtractedSubject[];
+}
+
+export interface CompletePendingHack extends PendingHack {
+    segments: {
+        favouriteQuote: Segment;
+        inANutshell: Segment;
+        introduction: Segment;
+        insights: [
+            Segment,
+            Segment,
+            Segment
+        ];
+        conclusion: Segment;
+        // composite segments
+        overview: Segment;
+        shareableOverview: Segment;
+        hereAreTheInsights: Segment;
+        putInAction?: Segment;
+    };
+    subjects: ExtractedSubject[];
+}
+
+export type CompletePendingHackWithPutInAction = CompletePendingHack & {
+    segments: {
+        putInAction: Segment;
+    }
+};

package/src/segment/segment-commands.ts

@@ -0,0 +1,70 @@
+import { SupportedLocale } from '../localisation/supported-locales';
+import { SegmentType } from './segment';
+
+export interface StandaloneSegmentCard {
+    markdown: string;
+}
+
+export interface StandaloneSegmentAction {
+    title: string;
+    cards: StandaloneSegmentCard[];
+}
+
+export interface StandaloneSegmentSection {
+    heading?: string;
+    cards: StandaloneSegmentCard[];
+}
+
+export interface CommandSegment {
+    type: SegmentType;
+    // @deprecated use hackTitle, hackType and hackContributors
+    source?: {
+        id: string;
+        type: string;
+        contributors: {
+            name: string;
+        }[];
+        title: string;
+    };
+    hackCoverUrl?: string;
+    hackId: string;
+    hackTitle: string;
+    hackType: 'book' | 'course' | 'documentary' | 'podcast' | 'original';
+    hackContributors: {
+        name: string;
+    }[];
+    locale: SupportedLocale;
+}
+export interface StandaloneSegment extends CommandSegment {
+    title?: string;
+    keywords?: string[];
+    sections: StandaloneSegmentSection[];
+    actions?: StandaloneSegmentAction[];
+    textSummary?: string;
+}
+
+export interface CompositeSegment extends CommandSegment {
+    subSegments: StandaloneSegment[];
+}
+
+export interface CreateSegmentCommand {
+    id: string;
+    type: 'CreateSegment';
+    payload: (CompositeSegment | StandaloneSegment);
+}
+
+export interface UpdateSegmentCommand {
+    id: string;
+    type: 'UpdateSegment';
+    payload: (CompositeSegment | StandaloneSegment) & {
+        segmentId: string;
+    };
+}
+
+export interface DeleteSegmentCommand {
+    id: string;
+    type: 'DeleteSegment';
+    payload: {
+        segmentId: string;
+    };
+}

package/src/segment/segment-with-voice.ts

@@ -0,0 +1,8 @@
+import { Segment } from './segment';
+
+// a segment with audio in a single voice, because having all voices in one segment would make the entity very large
+// the only difference is that it includes a voiceIdAndLanguage field, which can be used as a range key to find the segment for a specific voice
+// segmentsWithVoice may point to default or non-default voices
+export interface SegmentWithVoice extends Segment {
+    voiceIdAndLanguage: string;
+}

package/src/segment/segment.ts

@@ -0,0 +1,82 @@
+export interface SegmentVoice {
+    id: string;
+    language: string;
+    name: string;
+    countryCode: string;
+    speechProvider: string;
+}
+
+export interface Segment {
+    id: string;
+    v: number;
+    createdAt: string;
+    updatedAt: string;
+    hackId: string;
+    type: SegmentType;
+    title: string;
+    sections: SegmentSection[];
+    keywords: string[];
+    actions: SegmentAction[];
+    speech: SegmentSpeech[];
+    textSummary?: string;
+    lastUpdatedFromPendingSegmentId?: string;
+    hackType: string;
+    /** use @uptime.app/text-to-speech-contracts */
+    locale: string;
+}
+
+export type SegmentType =
+    'overview' | 'favourite-quote' | 'in-a-nutshell' |
+    'introduction' | 'here-are-the-insights' |
+    'insight-one' | 'insight-two' | 'insight-three' |
+    'put-in-action' | 'conclusion' |
+    'shareable-overview' | 'download-app-to-see-more';
+
+export type CardType = 'hack-cover' | 'action';
+
+export interface SegmentAction {
+    title: string;
+    cards: SegmentTextCard[];
+}
+
+export interface SegmentTextCard {
+    id: string;
+    markdown: string;
+    segmentType: SegmentType;
+    cardType?: CardType;
+    isTitle?: boolean;
+    speech?: TextCardSpeech[];
+}
+
+export interface SegmentSection {
+    heading?: string;
+    cards: SegmentTextCard[];
+}
+
+export interface SegmentSpeech {
+    voice: SegmentVoice;
+    withHeading: {
+        url: string;
+        lengthSeconds: number;
+    };
+    withoutHeading: {
+        url: string;
+        lengthSeconds: number;
+    };
+}
+
+export interface TextCardSpeech {
+    voiceId: string;
+    withHeading: {
+        timestamps: {
+            startsAt: number;
+            endsAt: number;
+        };
+    };
+    withoutHeading: {
+        timestamps: {
+            startsAt: number;
+            endsAt: number;
+        };
+    };
+}