@uptime.app/contracts 3.0.54-rc.2 → 3.0.54

package/src/hack/hack.ts

@@ -1,127 +1,127 @@
-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;
-    tenant?: string;
-    sourceId?: string;
-    title: string;
-    themeId: string;
-
-    /** introduced Aug 2025. Will be on all hacks republished since then **/
-    publishCompletedAt?: 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[];
-
-    /** Added in October 2025. Internal use only.
-     * It surfaces the "trending" tag from editorialTags if it exists.
-     * It's a number, 1 meaning true, because DynamoDB does not allow Boolean attributes in indexes.
-    */
-    _isTrending?: number;
-
-    coverUrl?: string;
-    /** Added in July 2024. This is the URL of the cover image that is free to use without any copyright. */
-    copyrightFreeCoverUrl?: 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 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';
-}
+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;
+    tenant?: string;
+    sourceId?: string;
+    title: string;
+    themeId: string;
+
+    /** introduced Aug 2025. Will be on all hacks republished since then **/
+    publishCompletedAt?: 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[];
+
+    /** Added in October 2025. Internal use only.
+     * It surfaces the "trending" tag from editorialTags if it exists.
+     * It's a number, 1 meaning true, because DynamoDB does not allow Boolean attributes in indexes.
+    */
+    _isTrending?: number;
+
+    coverUrl?: string;
+    /** Added in July 2024. This is the URL of the cover image that is free to use without any copyright. */
+    copyrightFreeCoverUrl?: 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 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/hack/publish-hack-command.ts

@@ -1,20 +1,20 @@
-export interface PublishHackCommandBody {
-    // a command needs an id and a version so that it can be more easily replayed
-    // for this specific PublishHack command, the id is the draftHackId and the version is the timestamp
-    id: string;
-    v: number;
-    draftHackId: string;
-    draftHackVersion: number;
-    hackId: string;
-    publishSource: PublishHackSource;
-    /** if no voice ids are specified then all voices are generated */
-    voiceIds?: string[];
-}
-
-export type PublishHackSource = 'web-app' | 'cms' | 'script' | 'translation';
-
-export interface PublishHackCommand {
-    id: string;
-    type: 'PublishHackCommand';
-    payload: PublishHackCommandBody;
-}
+export interface PublishHackCommandBody {
+    // a command needs an id and a version so that it can be more easily replayed
+    // for this specific PublishHack command, the id is the draftHackId and the version is the timestamp
+    id: string;
+    v: number;
+    draftHackId: string;
+    draftHackVersion: number;
+    hackId: string;
+    publishSource: PublishHackSource;
+    /** if no voice ids are specified then all voices are generated */
+    voiceIds?: string[];
+}
+
+export type PublishHackSource = 'web-app' | 'cms' | 'script' | 'translation';
+
+export interface PublishHackCommand {
+    id: string;
+    type: 'PublishHackCommand';
+    payload: PublishHackCommandBody;
+}

package/src/hack/republish-hack-command.ts

@@ -1,20 +1,20 @@
-import { PublishHackSource } from './publish-hack-command';
-
-/**
- * Republishes a hack. If the hack has never been published then the command will fail.
- * Will republish the current draft version and use the current hacks voices. Will not use new voices
- */
-export interface RepublishHackCommandBody {
-    id: string;
-    v: number;
-    hackId: string;
-    publishSource: PublishHackSource;
-    /** will skip the republished if the hack as been published since this date. ISO date format */
-    skipIfPublishedSince?: string;
-}
-
-export interface RepublishHackCommand {
-    id: string;
-    type: 'RepublishHack';
-    payload: RepublishHackCommandBody;
-}
+import { PublishHackSource } from './publish-hack-command';
+
+/**
+ * Republishes a hack. If the hack has never been published then the command will fail.
+ * Will republish the current draft version and use the current hacks voices. Will not use new voices
+ */
+export interface RepublishHackCommandBody {
+    id: string;
+    v: number;
+    hackId: string;
+    publishSource: PublishHackSource;
+    /** will skip the republished if the hack as been published since this date. ISO date format */
+    skipIfPublishedSince?: string;
+}
+
+export interface RepublishHackCommand {
+    id: string;
+    type: 'RepublishHack';
+    payload: RepublishHackCommandBody;
+}

package/src/hack-mapping/access-helper.ts

@@ -1,6 +1,6 @@
-export function hackIsInUptimeCatalogue({acl}: {acl: string[]}): boolean {
-    if (!acl) {
-        return false;
-    }
-    return acl.includes('catalogue:uptime');
-}
+export function hackIsInUptimeCatalogue({acl}: {acl: string[]}): boolean {
+    if (!acl) {
+        return false;
+    }
+    return acl.includes('catalogue:uptime');
+}

package/src/hack-mapping/app-full-hack.test.ts

@@ -1,13 +1,13 @@
-import { EnrichedHack } from '@uptime.app/contracts';
-import ENRICHED_HACK from './test-data/enriched-hack.json';
-import EXPECTED_APP_FULL_HACK from './test-data/expected-app-full-hack.json';
-import { mapToAppFullHack } from './app-full-hack';
-
-describe('converting an EnrichedHack to an AppFullHack', () => {
-
-    test('it returns the expected fields', () => {
-        const fullHackData = ENRICHED_HACK as any as EnrichedHack;
-        const fullHack = mapToAppFullHack(fullHackData);
-        expect(fullHack).toEqual(EXPECTED_APP_FULL_HACK);
-    });
-});
+import { EnrichedHack } from '@uptime.app/contracts';
+import ENRICHED_HACK from './test-data/enriched-hack.json';
+import EXPECTED_APP_FULL_HACK from './test-data/expected-app-full-hack.json';
+import { mapToAppFullHack } from './app-full-hack';
+
+describe('converting an EnrichedHack to an AppFullHack', () => {
+
+    test('it returns the expected fields', () => {
+        const fullHackData = ENRICHED_HACK as any as EnrichedHack;
+        const fullHack = mapToAppFullHack(fullHackData);
+        expect(fullHack).toEqual(EXPECTED_APP_FULL_HACK);
+    });
+});

package/src/hack-mapping/app-full-hack.ts

@@ -1,14 +1,14 @@
-import { AppFullHack } from '../app-hack/app-full-hack';
-import { EnrichedHack } from '../enriched-hack/enriched-hack';
-import { mapToAppRestrictedHack } from './app-restricted-hack';
-import { removeUndefinedFields } from './remove-undefined-fields';
-
-export function mapToAppFullHack(hack: EnrichedHack): AppFullHack {
-    const appHack = mapToAppRestrictedHack(hack);
-    // allow access to all segments
-    const segments = removeUndefinedFields(hack.segments);
-    return removeUndefinedFields({
-        ...appHack,
-        segments
-    });
-}
+import { AppFullHack } from '../app-hack/app-full-hack';
+import { EnrichedHack } from '../enriched-hack/enriched-hack';
+import { mapToAppRestrictedHack } from './app-restricted-hack';
+import { removeUndefinedFields } from './remove-undefined-fields';
+
+export function mapToAppFullHack(hack: EnrichedHack): AppFullHack {
+    const appHack = mapToAppRestrictedHack(hack);
+    // allow access to all segments
+    const segments = removeUndefinedFields(hack.segments);
+    return removeUndefinedFields({
+        ...appHack,
+        segments
+    });
+}

package/src/hack-mapping/app-hack-metadata.test.ts

@@ -1,22 +1,22 @@
-import { EnrichedHack } from '@uptime.app/contracts';
-import ENRICHED_HACK from './test-data/enriched-hack.json';
-import EXPECTED_APP_HACK_METADATA from './test-data/expected-app-hack-metadata.json';
-import { mapToAppHackMetadata } from './app-hack-metadata';
-describe('converting an EnrichedHack to an AppHackMetadata', () => {
-
-    test('it returns the expected fields', () => {
-        const appHackMetadataData = ENRICHED_HACK as any as EnrichedHack;
-        const appHackMetadata = mapToAppHackMetadata(appHackMetadataData);
-        expect(appHackMetadata).toEqual(EXPECTED_APP_HACK_METADATA);
-    });
-
-    test('a hack not in the uptime catalogue has shareScope set to private', () => {
-        const appHackMetadata = mapToAppHackMetadata({...ENRICHED_HACK, acl: ['catalogue:not-uptime']} as EnrichedHack);
-        expect(appHackMetadata.shareScope).toBe('private');
-    });
-
-    test('a hack not included on the website has shareScope set to private', () => {
-        const appHackMetadata = mapToAppHackMetadata({...ENRICHED_HACK, includeInWebsite: false} as EnrichedHack);
-        expect(appHackMetadata.shareScope).toBe('private');
-    });
-});
+import { EnrichedHack } from '@uptime.app/contracts';
+import ENRICHED_HACK from './test-data/enriched-hack.json';
+import EXPECTED_APP_HACK_METADATA from './test-data/expected-app-hack-metadata.json';
+import { mapToAppHackMetadata } from './app-hack-metadata';
+describe('converting an EnrichedHack to an AppHackMetadata', () => {
+
+    test('it returns the expected fields', () => {
+        const appHackMetadataData = ENRICHED_HACK as any as EnrichedHack;
+        const appHackMetadata = mapToAppHackMetadata(appHackMetadataData);
+        expect(appHackMetadata).toEqual(EXPECTED_APP_HACK_METADATA);
+    });
+
+    test('a hack not in the uptime catalogue has shareScope set to private', () => {
+        const appHackMetadata = mapToAppHackMetadata({...ENRICHED_HACK, acl: ['catalogue:not-uptime']} as EnrichedHack);
+        expect(appHackMetadata.shareScope).toBe('private');
+    });
+
+    test('a hack not included on the website has shareScope set to private', () => {
+        const appHackMetadata = mapToAppHackMetadata({...ENRICHED_HACK, includeInWebsite: false} as EnrichedHack);
+        expect(appHackMetadata.shareScope).toBe('private');
+    });
+});

package/src/hack-mapping/app-hack-metadata.ts

@@ -1,82 +1,82 @@
-import { removeUndefinedFields } from './remove-undefined-fields';
-import { hackIsInUptimeCatalogue } from './access-helper';
-import { EnrichedHack } from '../enriched-hack/enriched-hack';
-import { AppHackMetadata } from '../app-hack/app-hack-metadata';
-
-export function mapToAppHackMetadata(hack: EnrichedHack): AppHackMetadata {
-    // This function purposely picks the required fields from the EnrichedHack rather than deleting the unnecessary fields from EnrichedHack
-    // This ensures that if the EnrichedHack model is updated then those extra fields are not returned accidentally.
-    // This means that a service will not reflect any updated fields until it updates this module
-    return removeUndefinedFields({
-        id: hack.id,
-        title: hack.title,
-        owner: hack.owner,
-        v: hack.v,
-        hackVersion: hack.hackVersion,
-        createdAt: hack.createdAt,
-        updatedAt: hack.updatedAt,
-        baseLocaleHackId: hack.baseLocaleHackId,
-        language: hack.language,
-        locale: hack.locale,
-        acl: hack.acl,
-        themeId: hack.theme.id,
-        isHidden: hack.isHidden,
-        editorialTags: hack.editorialTags,
-        coverUrl: hack.coverUrl,
-        description: hack.description,
-        segments: toHackAppMetadataSegments(hack.segments),
-        topics: hack.topics,
-        contributors: hack.contributors,
-        type: hack.type,
-        sourceData: hack.sourceData,
-        // todo - should we pick the required fields from profile rather than the entire object?
-        profile: hack.profile,
-        timeSaved: hack.timeSaved,
-        estimatedTimeSaved: hack.estimatedTimeSaved,
-        shareScope: getShareScope(hack),
-        catalogues: aclToCatalogues(hack.acl),
-        tenantDisplayName: hack.tenantDisplayName
-    });
-}
-
-function toHackAppMetadataSegments(segments: EnrichedHack['segments']): AppHackMetadata['segments'] {
-    return removeUndefinedFields({
-        favouriteQuote: {
-            id: segments.favouriteQuote.id,
-        },
-        inANutshell: {
-            id: segments.inANutshell.id,
-        },
-        introduction: {
-            id: segments.introduction.id,
-        },
-        insights: segments.insights.map(insight => ({
-            id: insight.id,
-        })),
-        conclusion: {
-            id: segments.conclusion.id,
-        },
-        overview: {
-            id: segments.overview.id,
-        },
-        shareableOverview: {
-            id: segments.shareableOverview.id,
-        },
-        hereAreTheInsights: {
-            id: segments.hereAreTheInsights.id,
-        },
-        putInAction: segments.putInAction && {
-            id: segments.putInAction.id,
-        },
-    });
-}
-
-function getShareScope(hack: {acl: string[]; includeInWebsite: boolean}): 'public' | 'private' {
-    return (hack.includeInWebsite && hackIsInUptimeCatalogue(hack)) ? 'public' : 'private';
-}
-
-function aclToCatalogues(acl: string[]): string[] {
-    return acl
-        .filter(entry => entry.startsWith('catalogue:'))
-        .map(entry => entry.replace('catalogue:', ''));
-}
+import { removeUndefinedFields } from './remove-undefined-fields';
+import { hackIsInUptimeCatalogue } from './access-helper';
+import { EnrichedHack } from '../enriched-hack/enriched-hack';
+import { AppHackMetadata } from '../app-hack/app-hack-metadata';
+
+export function mapToAppHackMetadata(hack: EnrichedHack): AppHackMetadata {
+    // This function purposely picks the required fields from the EnrichedHack rather than deleting the unnecessary fields from EnrichedHack
+    // This ensures that if the EnrichedHack model is updated then those extra fields are not returned accidentally.
+    // This means that a service will not reflect any updated fields until it updates this module
+    return removeUndefinedFields({
+        id: hack.id,
+        title: hack.title,
+        owner: hack.owner,
+        v: hack.v,
+        hackVersion: hack.hackVersion,
+        createdAt: hack.createdAt,
+        updatedAt: hack.updatedAt,
+        baseLocaleHackId: hack.baseLocaleHackId,
+        language: hack.language,
+        locale: hack.locale,
+        acl: hack.acl,
+        themeId: hack.theme.id,
+        isHidden: hack.isHidden,
+        editorialTags: hack.editorialTags,
+        coverUrl: hack.coverUrl,
+        description: hack.description,
+        segments: toHackAppMetadataSegments(hack.segments),
+        topics: hack.topics,
+        contributors: hack.contributors,
+        type: hack.type,
+        sourceData: hack.sourceData,
+        // todo - should we pick the required fields from profile rather than the entire object?
+        profile: hack.profile,
+        timeSaved: hack.timeSaved,
+        estimatedTimeSaved: hack.estimatedTimeSaved,
+        shareScope: getShareScope(hack),
+        catalogues: aclToCatalogues(hack.acl),
+        tenantDisplayName: hack.tenantDisplayName
+    });
+}
+
+function toHackAppMetadataSegments(segments: EnrichedHack['segments']): AppHackMetadata['segments'] {
+    return removeUndefinedFields({
+        favouriteQuote: {
+            id: segments.favouriteQuote.id,
+        },
+        inANutshell: {
+            id: segments.inANutshell.id,
+        },
+        introduction: {
+            id: segments.introduction.id,
+        },
+        insights: segments.insights.map(insight => ({
+            id: insight.id,
+        })),
+        conclusion: {
+            id: segments.conclusion.id,
+        },
+        overview: {
+            id: segments.overview.id,
+        },
+        shareableOverview: {
+            id: segments.shareableOverview.id,
+        },
+        hereAreTheInsights: {
+            id: segments.hereAreTheInsights.id,
+        },
+        putInAction: segments.putInAction && {
+            id: segments.putInAction.id,
+        },
+    });
+}
+
+function getShareScope(hack: {acl: string[]; includeInWebsite: boolean}): 'public' | 'private' {
+    return (hack.includeInWebsite && hackIsInUptimeCatalogue(hack)) ? 'public' : 'private';
+}
+
+function aclToCatalogues(acl: string[]): string[] {
+    return acl
+        .filter(entry => entry.startsWith('catalogue:'))
+        .map(entry => entry.replace('catalogue:', ''));
+}

package/src/hack-mapping/app-restricted-hack.test.ts

@@ -1,12 +1,12 @@
-import { EnrichedHack } from '@uptime.app/contracts';
-import ENRICHED_HACK from './test-data/enriched-hack.json';
-import EXPECTED_APP_RESTRICTED_HACK from './test-data/expected-app-restricted-hack.json';
-import { mapToAppRestrictedHack } from './app-restricted-hack';
-describe('converting an EnrichedHack to an AppRestrictedHack', () => {
-
-    test('it returns the expected fields', () => {
-        const enrichedHackData = ENRICHED_HACK as any as EnrichedHack;
-        const restrictedHack = mapToAppRestrictedHack(enrichedHackData);
-        expect(restrictedHack).toEqual(EXPECTED_APP_RESTRICTED_HACK);
-    });
-});
+import { EnrichedHack } from '@uptime.app/contracts';
+import ENRICHED_HACK from './test-data/enriched-hack.json';
+import EXPECTED_APP_RESTRICTED_HACK from './test-data/expected-app-restricted-hack.json';
+import { mapToAppRestrictedHack } from './app-restricted-hack';
+describe('converting an EnrichedHack to an AppRestrictedHack', () => {
+
+    test('it returns the expected fields', () => {
+        const enrichedHackData = ENRICHED_HACK as any as EnrichedHack;
+        const restrictedHack = mapToAppRestrictedHack(enrichedHackData);
+        expect(restrictedHack).toEqual(EXPECTED_APP_RESTRICTED_HACK);
+    });
+});