@zivue/zuuid 0.1.0

package/dist/providers/tmdb/tv.js

@@ -0,0 +1,522 @@
+import { createZuuidData } from "../../entity.js";
+import { providerZuuid } from "../../identity.js";
+import { attachSourceMetadata, createSourceRecord } from "../../source.js";
+import { TMDB_BACKDROP_BASE_URL, TMDB_POSTER_BASE_URL, TMDB_PROVIDER } from "./constants.js";
+export const TMDB_TV_CATEGORY = "tv";
+export const ZUUID_TV_CATEGORY = "tvshow";
+export async function fetchTmdbTvSourceRecord(provider, input) {
+    const id = String(input.id).trim();
+    if (!id) {
+        throw new Error("TMDB tv id must not be empty");
+    }
+    if (!/^\d+$/.test(id)) {
+        throw new Error(`TMDB tv id must be numeric: ${id}`);
+    }
+    const payload = await provider.getJson(`/tv/${id}`, {
+        language: provider.language,
+        append_to_response: "aggregate_credits,external_ids,images,keywords,recommendations,similar,translations,content_ratings"
+    });
+    if (!payload) {
+        return undefined;
+    }
+    return createSourceRecord({
+        source: { provider: TMDB_PROVIDER, category: TMDB_TV_CATEGORY, externalId: id },
+        payload: payload
+    });
+}
+export async function searchTmdbTvSourceRecords(provider, input) {
+    const payload = await fetchTmdbTvSearchResults(provider, input);
+    return {
+        results: await sourceRecordsFromSearchResults(TMDB_TV_CATEGORY, payload.results),
+        pagination: paginationFromTmdbSearchResponse(payload)
+    };
+}
+export async function searchTmdbTv(provider, input, options = {}) {
+    const payload = await fetchTmdbTvSearchResults(provider, input);
+    const searchResults = [];
+    for (const result of payload.results ?? []) {
+        if (!result.id) {
+            continue;
+        }
+        const externalId = String(result.id);
+        const title = stringField(result.name) ?? stringField(result.original_name);
+        if (!title) {
+            continue;
+        }
+        const zuuid = await providerZuuid({ provider: TMDB_PROVIDER, category: TMDB_TV_CATEGORY, externalId });
+        searchResults.push({
+            id: zuuid,
+            zuuid,
+            category: ZUUID_TV_CATEGORY,
+            title,
+            date: stringField(result.first_air_date) ?? null,
+            cover: mediaUrl(result.poster_path ?? undefined, options.posterBaseUrl ?? TMDB_POSTER_BASE_URL) ?? null,
+            rating: typeof result.vote_average === "number" ? result.vote_average : null,
+            weight: typeof result.popularity === "number" ? result.popularity : null,
+            relationType: null,
+            attribute: null,
+            order: null,
+            source: { source: TMDB_PROVIDER, category: TMDB_TV_CATEGORY, value: externalId }
+        });
+    }
+    return {
+        results: searchResults,
+        pagination: paginationFromTmdbSearchResponse(payload)
+    };
+}
+async function fetchTmdbTvSearchResults(provider, input) {
+    const query = searchQuery(input.query, "TMDB tv search query");
+    const payload = await provider.getJson("/search/tv", {
+        ...searchParams(provider, input),
+        query,
+        ...(input.firstAirDateYear !== undefined ? { first_air_date_year: String(input.firstAirDateYear) } : {})
+    });
+    return payload ?? {};
+}
+export async function transformTmdbTv(source, options = {}) {
+    if (source.source.provider !== TMDB_PROVIDER || source.source.category !== TMDB_TV_CATEGORY) {
+        throw new Error(`unsupported TMDB source: ${source.source.provider}:${source.source.category}`);
+    }
+    const payload = source.payload;
+    const tmdbId = tmdbTvId(source, payload);
+    const title = stringField(payload.name) ?? stringField(payload.original_name);
+    if (!title) {
+        throw new Error("missing required TMDB tv field: name");
+    }
+    const zuuid = await providerZuuid({
+        provider: TMDB_PROVIDER,
+        category: TMDB_TV_CATEGORY,
+        externalId: tmdbId
+    });
+    const data = createZuuidData({ zuuid, category: ZUUID_TV_CATEGORY, primaryTitle: title });
+    const firstAirDate = stringField(payload.first_air_date);
+    if (firstAirDate) {
+        validateDate(firstAirDate, "first_air_date");
+        data.primaryDate = firstAirDate;
+    }
+    if (typeof payload.vote_average === "number") {
+        data.rating = payload.vote_average;
+    }
+    const overview = stringField(payload.overview);
+    if (overview) {
+        data.descriptions.push({ language: stringField(payload.original_language), value: overview, source: TMDB_PROVIDER });
+    }
+    const originalName = stringField(payload.original_name);
+    if (originalName && originalName !== title) {
+        data.aliases.push({
+            value: originalName,
+            language: stringField(payload.original_language),
+            aliasType: "original_name",
+            isPrimary: false,
+            source: TMDB_PROVIDER
+        });
+    }
+    addTranslations(data, payload, title);
+    addExternalIds(data, payload);
+    addImage(data, "poster", payload.poster_path, options.posterBaseUrl ?? TMDB_POSTER_BASE_URL, true);
+    addImage(data, "backdrop", payload.backdrop_path, options.backdropBaseUrl ?? TMDB_BACKDROP_BASE_URL, false);
+    addImages(data, payload, options);
+    data.cover = data.media.find((media) => media.mediaCategory === "poster")?.url;
+    for (const genre of payload.genres ?? []) {
+        addTag(data, genre.name);
+    }
+    for (const keyword of payload.keywords?.results ?? []) {
+        addTag(data, keyword.name);
+    }
+    await addCreatedByRelations(data, payload);
+    await addAggregateCreditRelations(data, payload);
+    await addNamedRelations(data, payload.networks, "network", "network");
+    await addNamedRelations(data, payload.production_companies, "production_company", "company");
+    await addSeasonRelations(data, payload, tmdbId, options);
+    await addRelatedTv(data, "similar", payload.similar, options);
+    await addRelatedTv(data, "related", payload.recommendations, options);
+    addDetail(data, "original_language", payload.original_language);
+    addDetail(data, "status", payload.status);
+    addDetail(data, "show_type", payload.type);
+    addDetail(data, "tagline", payload.tagline);
+    addDetail(data, "homepage", payload.homepage);
+    addDetail(data, "first_air_date", payload.first_air_date);
+    addDetail(data, "last_air_date", payload.last_air_date);
+    addNumberDetail(data, "season_count", payload.number_of_seasons);
+    addNumberDetail(data, "episode_count", payload.number_of_episodes);
+    addNumberDetail(data, "vote_count", payload.vote_count);
+    addNumberDetail(data, "popularity", payload.popularity);
+    addBooleanDetail(data, "adult", payload.adult);
+    addBooleanDetail(data, "in_production", payload.in_production);
+    addBooleanDetail(data, "softcore", payload.softcore);
+    addNumberArrayDetail(data, "episode_run_time", payload.episode_run_time);
+    addArrayDetail(data, "languages", payload.languages);
+    addArrayDetail(data, "origin_country", payload.origin_country);
+    addTvCertifications(data, payload);
+    addStructuredDetail(data, "production_countries", payload.production_countries);
+    addStructuredDetail(data, "spoken_languages", payload.spoken_languages);
+    addStructuredDetail(data, "content_ratings", payload.content_ratings?.results);
+    addStructuredDetail(data, "last_episode_to_air", payload.last_episode_to_air);
+    addStructuredDetail(data, "next_episode_to_air", payload.next_episode_to_air);
+    addStructuredDetail(data, "watch_providers", payload.watch_providers?.results);
+    return attachSourceMetadata(data, source);
+}
+function tmdbTvId(source, payload) {
+    const sourceId = source.source.externalId.trim();
+    if (sourceId) {
+        return sourceId;
+    }
+    const payloadId = payload.id === undefined ? undefined : String(payload.id).trim();
+    if (payloadId) {
+        return payloadId;
+    }
+    throw new Error("missing required TMDB tv field: id");
+}
+function addExternalIds(data, payload) {
+    const ids = payload.external_ids ?? {};
+    addExternalId(data, "imdb", ZUUID_TV_CATEGORY, stringField(ids.imdb_id ?? undefined));
+    addExternalId(data, "tvdb", ZUUID_TV_CATEGORY, numberOrStringField(ids.tvdb_id));
+    addExternalId(data, "tvrage", ZUUID_TV_CATEGORY, numberOrStringField(ids.tvrage_id));
+    addExternalId(data, "wikidata", ZUUID_TV_CATEGORY, stringField(ids.wikidata_id ?? undefined));
+    addExternalId(data, "facebook", ZUUID_TV_CATEGORY, stringField(ids.facebook_id ?? undefined));
+    addExternalId(data, "instagram", ZUUID_TV_CATEGORY, stringField(ids.instagram_id ?? undefined));
+    addExternalId(data, "twitter", ZUUID_TV_CATEGORY, stringField(ids.twitter_id ?? undefined));
+}
+function addExternalId(data, source, category, value) {
+    if (!value || data.externalIds.some((id) => id.source === source && id.category === category && id.value === value)) {
+        return;
+    }
+    data.externalIds.push({ source, category, value });
+}
+function addTranslations(data, payload, primaryTitle) {
+    for (const item of payload.translations?.translations ?? []) {
+        const title = stringField(item.data?.name);
+        const language = stringField(item.iso_639_1);
+        const region = stringField(item.iso_3166_1);
+        if (title && title !== primaryTitle) {
+            data.aliases.push({ value: title, language, region, aliasType: "translation", isPrimary: false, source: TMDB_PROVIDER });
+        }
+        const overview = stringField(item.data?.overview);
+        if (overview) {
+            data.descriptions.push({ language, region, value: overview, source: TMDB_PROVIDER });
+        }
+    }
+}
+async function addCreatedByRelations(data, payload) {
+    for (const creator of payload.created_by ?? []) {
+        if (!creator.id || !creator.name) {
+            continue;
+        }
+        const id = String(creator.id);
+        const zuuid = await providerZuuid({ provider: TMDB_PROVIDER, category: "person", externalId: id });
+        data.relations.push({
+            id: zuuid,
+            zuuid,
+            relationType: "creator",
+            direction: "outgoing",
+            title: creator.name,
+            category: "person",
+            date: null,
+            cover: mediaUrl(creator.profile_path ?? undefined, TMDB_POSTER_BASE_URL) ?? null,
+            rating: null,
+            weight: null,
+            source: TMDB_PROVIDER,
+            externalId: id,
+            attribute: null,
+            order: null
+        });
+    }
+}
+async function addAggregateCreditRelations(data, payload) {
+    for (const cast of payload.aggregate_credits?.cast ?? []) {
+        if (!cast.id || !cast.name) {
+            continue;
+        }
+        const id = String(cast.id);
+        const primaryRole = cast.roles?.[0];
+        const zuuid = await providerZuuid({ provider: TMDB_PROVIDER, category: "person", externalId: id });
+        data.relations.push({
+            id: zuuid,
+            zuuid,
+            relationType: "performed_by",
+            direction: "outgoing",
+            title: cast.name,
+            category: "person",
+            date: null,
+            cover: mediaUrl(cast.profile_path ?? undefined, TMDB_POSTER_BASE_URL) ?? null,
+            rating: null,
+            weight: null,
+            source: TMDB_PROVIDER,
+            externalId: id,
+            attribute: stringField(primaryRole?.character) ?? null,
+            order: 0,
+            data: cast
+        });
+    }
+    for (const crew of payload.aggregate_credits?.crew ?? []) {
+        if (!crew.id || !crew.name) {
+            continue;
+        }
+        const id = String(crew.id);
+        const primaryJob = crew.jobs?.[0]?.job ?? crew.department;
+        const zuuid = await providerZuuid({ provider: TMDB_PROVIDER, category: "person", externalId: id });
+        data.relations.push({
+            id: zuuid,
+            zuuid,
+            relationType: primaryJob ? relationForCrewJob(primaryJob) : "related_to",
+            direction: "outgoing",
+            title: crew.name,
+            category: "person",
+            date: null,
+            cover: mediaUrl(crew.profile_path ?? undefined, TMDB_POSTER_BASE_URL) ?? null,
+            rating: null,
+            weight: null,
+            source: TMDB_PROVIDER,
+            externalId: id,
+            attribute: stringField(primaryJob) ?? null,
+            order: 0,
+            data: crew
+        });
+    }
+}
+async function addNamedRelations(data, values, relationType, category) {
+    for (const [index, value] of (values ?? []).entries()) {
+        if (!value.id || !value.name) {
+            continue;
+        }
+        const id = String(value.id);
+        const zuuid = await providerZuuid({ provider: TMDB_PROVIDER, category, externalId: id });
+        data.relations.push({
+            id: zuuid,
+            zuuid,
+            relationType,
+            direction: "outgoing",
+            title: value.name,
+            category,
+            date: null,
+            cover: mediaUrl("logo_path" in value ? value.logo_path ?? undefined : undefined, TMDB_POSTER_BASE_URL) ?? null,
+            rating: null,
+            weight: null,
+            source: TMDB_PROVIDER,
+            externalId: id,
+            attribute: stringField(value.origin_country) ?? null,
+            order: index
+        });
+    }
+}
+async function addSeasonRelations(data, payload, tvId, options) {
+    for (const season of payload.seasons ?? []) {
+        if (season.season_number === undefined || !season.name) {
+            continue;
+        }
+        const externalId = `${tvId}-${season.season_number}`;
+        const zuuid = await providerZuuid({ provider: TMDB_PROVIDER, category: "tvseason", externalId });
+        data.relations.push({
+            id: zuuid,
+            zuuid,
+            relationType: "contains",
+            direction: "outgoing",
+            title: season.name,
+            category: "tvseason",
+            date: stringField(season.air_date) ?? null,
+            cover: mediaUrl(season.poster_path ?? undefined, options.posterBaseUrl ?? TMDB_POSTER_BASE_URL) ?? null,
+            rating: null,
+            weight: null,
+            source: TMDB_PROVIDER,
+            externalId,
+            attribute: `season:${season.name}`,
+            order: season.season_number,
+            data: season
+        });
+        addImage(data, "season_poster", season.poster_path ?? undefined, options.posterBaseUrl ?? TMDB_POSTER_BASE_URL, false);
+    }
+}
+async function addRelatedTv(data, recommendationType, list, options) {
+    for (const item of list?.results ?? []) {
+        if (!item.id) {
+            continue;
+        }
+        const id = String(item.id);
+        const title = stringField(item.name) ?? stringField(item.original_name);
+        if (!title) {
+            continue;
+        }
+        const zuuid = await providerZuuid({ provider: TMDB_PROVIDER, category: TMDB_TV_CATEGORY, externalId: id });
+        const rating = typeof item.vote_average === "number" ? item.vote_average : null;
+        data.recommendations.push({
+            id: zuuid,
+            zuuid,
+            recommendationType,
+            relationType: recommendationType,
+            weight: rating,
+            source: TMDB_PROVIDER,
+            title,
+            category: ZUUID_TV_CATEGORY,
+            date: stringField(item.first_air_date) ?? null,
+            cover: mediaUrl(item.poster_path ?? undefined, options.posterBaseUrl ?? TMDB_POSTER_BASE_URL) ?? null,
+            rating,
+            externalId: id,
+            attribute: null,
+            order: null,
+            reasons: [recommendationType]
+        });
+    }
+}
+function addImages(data, payload, options) {
+    for (const image of payload.images?.posters ?? []) {
+        addImage(data, "poster", image.file_path, options.posterBaseUrl ?? TMDB_POSTER_BASE_URL, false, image);
+    }
+    for (const image of payload.images?.backdrops ?? []) {
+        addImage(data, "backdrop", image.file_path, options.backdropBaseUrl ?? TMDB_BACKDROP_BASE_URL, false, image);
+    }
+    for (const image of payload.images?.logos ?? []) {
+        addImage(data, "logo", image.file_path, options.posterBaseUrl ?? TMDB_POSTER_BASE_URL, false, image);
+    }
+}
+function addImage(data, mediaCategory, path, baseUrl, isPrimary, image) {
+    const url = mediaUrl(path, baseUrl);
+    if (!url) {
+        return;
+    }
+    data.media.push({
+        url,
+        mediaType: "image",
+        mediaCategory,
+        width: image?.width,
+        height: image?.height,
+        isPrimary,
+        data: image,
+        source: TMDB_PROVIDER
+    });
+}
+function addTag(data, value) {
+    const tag = stringField(value)?.toLowerCase();
+    if (tag && !data.tags.includes(tag)) {
+        data.tags.push(tag);
+    }
+}
+function addDetail(data, key, value) {
+    const normalized = stringField(value);
+    if (normalized) {
+        data.details.push({ key, value: normalized, source: TMDB_PROVIDER });
+    }
+}
+function addNumberDetail(data, key, value) {
+    if (typeof value === "number") {
+        data.details.push({ key, value, source: TMDB_PROVIDER });
+    }
+}
+function addBooleanDetail(data, key, value) {
+    if (typeof value === "boolean") {
+        data.details.push({ key, value, source: TMDB_PROVIDER });
+    }
+}
+function addNumberArrayDetail(data, key, value) {
+    if (value?.length) {
+        data.details.push({ key, value, source: TMDB_PROVIDER });
+    }
+}
+function addArrayDetail(data, key, value) {
+    if (value?.length) {
+        data.details.push({ key, value, source: TMDB_PROVIDER });
+    }
+}
+function addTvCertifications(data, payload) {
+    const certifications = [];
+    for (const item of payload.content_ratings?.results ?? []) {
+        const region = stringField(item.iso_3166_1);
+        const certification = stringField(item.rating);
+        if (!region || !certification) {
+            continue;
+        }
+        certifications.push({
+            region,
+            certification,
+            descriptors: item.descriptors ?? []
+        });
+    }
+    if (!certifications.length) {
+        return;
+    }
+    data.details.push({
+        key: "certifications",
+        value: certifications,
+        source: TMDB_PROVIDER
+    });
+}
+function addStructuredDetail(data, key, value) {
+    if (value === undefined || value === null || (Array.isArray(value) && value.length === 0)) {
+        return;
+    }
+    data.details.push({ key, value, source: TMDB_PROVIDER });
+}
+function stringField(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : undefined;
+}
+function numberOrStringField(value) {
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    return stringField(String(value));
+}
+function relationForCrewJob(job) {
+    switch (job.toLowerCase()) {
+        case "creator":
+        case "executive producer":
+        case "producer":
+            return "produced_by";
+        case "director":
+            return "directed_by";
+        case "writer":
+        case "screenplay":
+        case "novel":
+            return "authored_by";
+        default:
+            return "related_to";
+    }
+}
+function mediaUrl(path, baseUrl) {
+    const value = stringField(path);
+    if (!value) {
+        return undefined;
+    }
+    if (value.startsWith("http://") || value.startsWith("https://")) {
+        return value;
+    }
+    return baseUrl ? `${baseUrl.replace(/\/$/, "")}/${value.replace(/^\//, "")}` : value;
+}
+function validateDate(value, field) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00.000Z`))) {
+        throw new Error(`invalid TMDB tv field ${field}: ${value}`);
+    }
+}
+function searchQuery(value, field) {
+    const normalized = stringField(value);
+    if (!normalized) {
+        throw new Error(`${field} must not be empty`);
+    }
+    return normalized;
+}
+function searchParams(provider, input) {
+    return {
+        language: input.language ?? provider.language,
+        page: String(input.page ?? 1),
+        include_adult: String(input.includeAdult ?? false)
+    };
+}
+async function sourceRecordsFromSearchResults(category, results) {
+    const records = [];
+    for (const result of results ?? []) {
+        if (!result.id) {
+            continue;
+        }
+        records.push(await createSourceRecord({
+            source: { provider: TMDB_PROVIDER, category, externalId: String(result.id) },
+            payload: result
+        }));
+    }
+    return records;
+}
+function paginationFromTmdbSearchResponse(payload) {
+    return {
+        page: payload.page ?? 1,
+        totalPages: payload.total_pages ?? 0,
+        totalResults: payload.total_results ?? 0
+    };
+}

package/dist/providers/tmdb/types.d.ts

@@ -0,0 +1,36 @@
+export type TmdbCredential = {
+    apiKey: string;
+    bearerToken?: never;
+} | {
+    apiKey?: never;
+    bearerToken: string;
+};
+export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export type TmdbProviderOptions = TmdbCredential & {
+    apiBase?: string;
+    fetch?: FetchLike;
+    posterBaseUrl?: string | null;
+    backdropBaseUrl?: string | null;
+    language?: string;
+};
+export type TmdbTransformOptions = {
+    posterBaseUrl?: string | null;
+    backdropBaseUrl?: string | null;
+};
+export type TmdbSearchInput = {
+    query: string;
+    page?: number;
+    includeAdult?: boolean;
+    language?: string;
+    region?: string;
+    year?: number;
+    primaryReleaseYear?: number;
+    firstAirDateYear?: number;
+};
+export type TmdbSearchResponse<T> = {
+    page?: number;
+    results?: T[];
+    total_pages?: number;
+    total_results?: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/providers/tmdb/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/providers/tmdb/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GACtB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAAE,GACvC;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvF,MAAM,MAAM,mBAAmB,GAAG,cAAc,GAAG;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC"}

package/dist/providers/tmdb/types.js

@@ -0,0 +1 @@
+export {};

package/dist/source.d.ts

@@ -0,0 +1,35 @@
+import type { JsonValue } from "./types.js";
+import type { ZuuidData } from "./entity.js";
+export type SourceRecordRef = {
+    provider: string;
+    category: string;
+    externalId: string;
+};
+export type ExternalId = {
+    source: string;
+    category: string;
+    value: string;
+};
+export type Provenance = {
+    source: SourceRecordRef;
+    observedAt: string;
+    confidence?: number;
+    contentHash?: string;
+};
+export type SourceRecord = {
+    source: SourceRecordRef;
+    payload: JsonValue;
+    contentHash: string;
+    observedAt: string;
+    publishedAt?: string;
+};
+export type CreateSourceRecordInput = {
+    source: SourceRecordRef;
+    payload: JsonValue;
+    observedAt?: string | Date;
+    publishedAt?: string | Date;
+};
+export declare function createSourceRecord(input: CreateSourceRecordInput): Promise<SourceRecord>;
+export declare function attachSourceMetadata(dataset: ZuuidData, sourceRecord: SourceRecord, confidence?: number): ZuuidData;
+export declare function externalIdFromSource(source: SourceRecordRef): ExternalId;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,SAAS,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,SAAS,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC,CAY9F;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,EAClB,YAAY,EAAE,YAAY,EAC1B,UAAU,SAAM,GACf,SAAS,CAoBX;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU,CAMxE"}

package/dist/source.js

@@ -0,0 +1,53 @@
+import { stablePayloadHash } from "./hash.js";
+export async function createSourceRecord(input) {
+    return {
+        source: {
+            provider: input.source.provider,
+            category: input.source.category,
+            externalId: input.source.externalId
+        },
+        payload: input.payload,
+        contentHash: await stablePayloadHash(input.payload),
+        observedAt: normalizeTimestamp(input.observedAt ?? new Date()),
+        publishedAt: input.publishedAt ? normalizeTimestamp(input.publishedAt) : undefined
+    };
+}
+export function attachSourceMetadata(dataset, sourceRecord, confidence = 1.0) {
+    const next = structuredClone(dataset);
+    const externalId = externalIdFromSource(sourceRecord.source);
+    if (!next.externalIds.some((item) => sameExternalId(item, externalId))) {
+        next.externalIds.push(externalId);
+    }
+    const provenance = {
+        source: sourceRecord.source,
+        observedAt: sourceRecord.observedAt,
+        confidence,
+        contentHash: sourceRecord.contentHash
+    };
+    if (!next.provenance.some((item) => sameProvenance(item, provenance))) {
+        next.provenance.push(provenance);
+    }
+    return next;
+}
+export function externalIdFromSource(source) {
+    return {
+        source: source.provider,
+        category: source.category,
+        value: source.externalId
+    };
+}
+function normalizeTimestamp(value) {
+    return value instanceof Date ? value.toISOString() : value;
+}
+function sameSourceRef(a, b) {
+    return a.provider === b.provider && a.category === b.category && a.externalId === b.externalId;
+}
+function sameExternalId(a, b) {
+    return a.source === b.source && a.category === b.category && a.value === b.value;
+}
+function sameProvenance(a, b) {
+    return (sameSourceRef(a.source, b.source) &&
+        a.observedAt === b.observedAt &&
+        a.confidence === b.confidence &&
+        a.contentHash === b.contentHash);
+}

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAC7D,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/uuid.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeUuid(value: string): string;
+export declare function uuidV5(name: string, namespace: string): Promise<string>;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AAEA,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQnD;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc7E"}