@singi-labs/sifa-sdk 0.9.3 → 0.9.5

package/dist/index.d.cts

@@ -94,6 +94,10 @@ declare function getWorkplaceTypeLabel(value: string | undefined | null): string
 declare const PLATFORM_LABELS: {
     readonly bluesky: "Bluesky";
     readonly github: "GitHub";
+    readonly codeberg: "Codeberg";
+    readonly gitlab: "GitLab";
+    readonly forgejo: "Forgejo";
+    readonly gitea: "Gitea";
     readonly linkedin: "LinkedIn";
     readonly youtube: "YouTube";
     readonly twitter: "X (Twitter)";
@@ -166,6 +170,47 @@ declare function dedupeSkills(skills: ProfileSkill[]): MergedProfileSkill[];
  */
 declare function groupSkillsByCategory<T extends ProfileSkill>(skills: T[]): [string, T[]][];
 
+type ActivityTier = 'creation' | 'action' | 'filtered';
+interface TierMeta {
+    label: string | null;
+    description: string;
+    shownOnPublicProfile: boolean;
+}
+interface LexiconEntry {
+    tier: ActivityTier;
+    app?: string;
+    notes?: string;
+}
+interface ActivityTaxonomy {
+    version: string;
+    updated: string;
+    tiers: Record<ActivityTier, TierMeta>;
+    lexicons: Record<string, LexiconEntry>;
+}
+declare const ACTIVITY_TIERS: Readonly<ActivityTaxonomy>;
+/**
+ * Returns the activity tier for a given AT Protocol NSID.
+ * Returns 'filtered' for unknown/unclassified NSIDs (safe default — won't
+ * leak unknown records to public profile surfaces).
+ */
+declare function getActivityTier(nsid: string): ActivityTier;
+/**
+ * Returns the full lexicon entry (tier + app + notes), or null if unknown.
+ */
+declare function getLexiconEntry(nsid: string): LexiconEntry | null;
+/**
+ * Returns tier metadata (label, description, public visibility).
+ */
+declare function getTierMeta(tier: ActivityTier): TierMeta;
+/**
+ * Returns the taxonomy version + updated date for diagnostics and
+ * version-skew detection between SDK consumers and the canonical taxonomy.
+ */
+declare function getActivityTaxonomyVersion(): {
+    version: string;
+    updated: string;
+};
+
 /**
  * Format a date string as a relative time (e.g. "5m ago", "3d ago").
  * Returns an empty string for invalid or future dates.
@@ -259,6 +304,27 @@ declare function getDisplayLabel(displayName: string | undefined, handle: string
 declare function getPdsDisplayName(providerName: string): string;
 declare function detectPdsProvider(handle: string): PdsProvider | null;
 
+/**
+ * Limit runs of Unicode combining marks (`\p{M}`) to at most `maxPerBase`
+ * marks following any single base character. Defuses "Zalgo" text where
+ * dozens of stacked combining marks render outside the line box and bleed
+ * into neighbouring UI.
+ *
+ * `maxPerBase` defaults to 4 — high enough to preserve legitimate stacks
+ * in Thai, Arabic, Vietnamese, and IPA, low enough to neutralise the
+ * vertical-overflow attack vector.
+ */
+declare function limitCombiningMarks(value: string, maxPerBase?: number): string;
+/**
+ * Sanitise untrusted display text from PDS records before rendering in UI:
+ * - strips bidi formatting controls (LRM/RLM/LRE/RLE/PDF/LRO/RLO/LRI/RLI/FSI/PDI)
+ *   that can hijack reading order or crash `next/og` (see Satori LRM+emoji bug)
+ * - limits stacked combining marks (Zalgo defence)
+ *
+ * Preserves ZWJ (U+200D) so emoji sequences keep rendering.
+ */
+declare function sanitizeDisplayText(value: string, maxCombiningPerBase?: number): string;
+
 /**
  * Truncate a string to at most `maxLen` grapheme clusters, appending an
  * ellipsis when the string was shortened. Grapheme-aware so it never splits
@@ -306,6 +372,79 @@ declare function contrastRatio(color1: RgbColor, color2: RgbColor): number;
  */
 declare function meetsContrastAA(foreground: RgbColor, background: RgbColor): boolean;
 
+/**
+ * URL patterns per app, mirroring the sifa-web registry.
+ *
+ * These describe how to build a clickable URL for an activity card given
+ * the author's handle/did and the record rkey. The patterns are templates
+ * with `{handle}`, `{did}`, and `{rkey}` placeholders; each variable is
+ * URI-encoded when interpolated.
+ *
+ * Tier semantics:
+ * - `urlPattern`: per-item URL (a specific post/event/repo). Preferred.
+ * - `profileUrlPattern`: per-user profile URL on the app. Fallback.
+ *
+ * Apps without either pattern are not clickable.
+ */
+interface AppUrlPatterns {
+    urlPattern?: string;
+    profileUrlPattern?: string;
+}
+declare const APP_URL_PATTERNS: Readonly<Record<string, AppUrlPatterns>>;
+/**
+ * Map collection NSID prefixes to app ids. Order matters: longer / more
+ * specific prefixes must come before broader ones.
+ */
+declare const COLLECTION_TO_APP: ReadonlyArray<readonly [prefix: string, appId: string]>;
+
+/**
+ * An activity item as consumed by the Sifa activity-card components and
+ * the sifa-api external-URL health scanner. The shape mirrors the props
+ * the cards already use, so the resolver returns the same URL the UI
+ * renders.
+ */
+interface ActivityItemForUrl {
+    /** Collection NSID, e.g. "sh.tangled.graph.repo". */
+    collection: string;
+    /** The raw record from the PDS / API. */
+    record: Record<string, unknown>;
+    /** Full at-uri of the record (used by collections that derive URL from uri). */
+    uri: string;
+    /** Record key. */
+    rkey: string;
+    /** DID of the author of the record. */
+    authorDid: string;
+    /** Optional handle (cards prefer handle in URL paths when available). */
+    authorHandle?: string;
+}
+/**
+ * Map a collection NSID to its app id, mirroring the sifa-web prefix map.
+ *
+ * Falls back to the first two NSID segments (e.g. "org.hyperboards") when
+ * the prefix is not registered, matching the existing card behaviour.
+ */
+declare function getAppIdForCollection(collection: string): string;
+/**
+ * Resolve the canonical clickable URL for an activity item — the same URL
+ * the activity-card UI in sifa-web renders.
+ *
+ * Returns `null` when no link is appropriate (the card would render
+ * non-clickable, or hide itself entirely).
+ *
+ * Used by:
+ * - sifa-web activity cards (single source of truth for href)
+ * - sifa-api external-URL health scanner (must match what the UI links to,
+ *   so broken-link detection lines up with what users actually click)
+ *
+ * Resolution order:
+ * 1. Per-collection bespoke logic (tangled, kipclip, margin, smokesignal
+ *    rsvp, standard documents). These mirror the inline logic in the
+ *    individual card components.
+ * 2. Generic `record.url` field (used by hyperboards and similar).
+ * 3. Pattern-based per-item / profile URL from the registry.
+ */
+declare function resolveCardUrl(item: ActivityItemForUrl): string | null;
+
 /**
  * Profile completeness scoring.
  *
@@ -393,4 +532,4 @@ declare function countFilledDimensions(input: ProfileDimensionInputs | Profile):
  */
 declare const SIFA_SDK_VERSION: string;
 
-export { CATEGORY_LABELS, CATEGORY_ORDER, COMPLETENESS_MAX_SCORE, CONTINENTS, COUNTRIES, type ContinentCode, DIMENSIONS_MAX_SCORE, type DimensionKey, type DimensionMap, EMPLOYMENT_TYPE_GROUPS, EMPLOYMENT_TYPE_LABELS, type EmploymentTypeGroup, type EmploymentTypeOption, INDUSTRY_OPTIONS, type IndustryOption, LocationValue, MIN_SKILLS, type MergedProfileSkill, OPEN_TO_OPTIONS, type OpenToOption, PLATFORM_LABELS, PLATFORM_OPTIONS, type PdsProvider, PdsProviderInfo, type PlatformId, Profile, type ProfileCompletion, type ProfileDimensionInputs, ProfileSkill, type RgbColor, SIFA_SDK_VERSION, SKILL_CATEGORIES, type SkillCategory, WORKPLACE_TYPE_LABELS, WORKPLACE_TYPE_OPTIONS, type WorkplaceTypeOption, certDateExtractor, completenessPercent, completenessScore, contrastRatio, countFilledDimensions, countryCodeToFlag, dateRangeExtractor, dedupeSkills, detectPdsProvider, dimensionsFromInputs, findIndustry, formatDistanceToNow, formatLocation, formatRelativeTime, getContinent, getDisplayLabel, getEmploymentTypeLabel, getFaviconUrl, getFilledDimensionsMap, getHandleStem, getIndustryLabelKey, getOpenToLabelKey, getPdsDisplayName, getPlatformLabel, getWorkplaceTypeLabel, groupSkillsByCategory, isKnownPlatform, isValidRgbColor, lexiconDateExtractor, meetsContrastAA, parseLocationString, pdsProviderFromApi, profileToDimensionInputs, relativeLuminance, rgbToString, sanitizeHandleInput, singleDateExtractor, sortByDateDesc, truncateGraphemes };
+export { ACTIVITY_TIERS, APP_URL_PATTERNS, type ActivityItemForUrl, type ActivityTaxonomy, type ActivityTier, type AppUrlPatterns, CATEGORY_LABELS, CATEGORY_ORDER, COLLECTION_TO_APP, COMPLETENESS_MAX_SCORE, CONTINENTS, COUNTRIES, type ContinentCode, DIMENSIONS_MAX_SCORE, type DimensionKey, type DimensionMap, EMPLOYMENT_TYPE_GROUPS, EMPLOYMENT_TYPE_LABELS, type EmploymentTypeGroup, type EmploymentTypeOption, INDUSTRY_OPTIONS, type IndustryOption, type LexiconEntry, LocationValue, MIN_SKILLS, type MergedProfileSkill, OPEN_TO_OPTIONS, type OpenToOption, PLATFORM_LABELS, PLATFORM_OPTIONS, type PdsProvider, PdsProviderInfo, type PlatformId, Profile, type ProfileCompletion, type ProfileDimensionInputs, ProfileSkill, type RgbColor, SIFA_SDK_VERSION, SKILL_CATEGORIES, type SkillCategory, type TierMeta, WORKPLACE_TYPE_LABELS, WORKPLACE_TYPE_OPTIONS, type WorkplaceTypeOption, certDateExtractor, completenessPercent, completenessScore, contrastRatio, countFilledDimensions, countryCodeToFlag, dateRangeExtractor, dedupeSkills, detectPdsProvider, dimensionsFromInputs, findIndustry, formatDistanceToNow, formatLocation, formatRelativeTime, getActivityTaxonomyVersion, getActivityTier, getAppIdForCollection, getContinent, getDisplayLabel, getEmploymentTypeLabel, getFaviconUrl, getFilledDimensionsMap, getHandleStem, getIndustryLabelKey, getLexiconEntry, getOpenToLabelKey, getPdsDisplayName, getPlatformLabel, getTierMeta, getWorkplaceTypeLabel, groupSkillsByCategory, isKnownPlatform, isValidRgbColor, lexiconDateExtractor, limitCombiningMarks, meetsContrastAA, parseLocationString, pdsProviderFromApi, profileToDimensionInputs, relativeLuminance, resolveCardUrl, rgbToString, sanitizeDisplayText, sanitizeHandleInput, singleDateExtractor, sortByDateDesc, truncateGraphemes };

package/dist/index.d.ts

@@ -94,6 +94,10 @@ declare function getWorkplaceTypeLabel(value: string | undefined | null): string
 declare const PLATFORM_LABELS: {
     readonly bluesky: "Bluesky";
     readonly github: "GitHub";
+    readonly codeberg: "Codeberg";
+    readonly gitlab: "GitLab";
+    readonly forgejo: "Forgejo";
+    readonly gitea: "Gitea";
     readonly linkedin: "LinkedIn";
     readonly youtube: "YouTube";
     readonly twitter: "X (Twitter)";
@@ -166,6 +170,47 @@ declare function dedupeSkills(skills: ProfileSkill[]): MergedProfileSkill[];
  */
 declare function groupSkillsByCategory<T extends ProfileSkill>(skills: T[]): [string, T[]][];
 
+type ActivityTier = 'creation' | 'action' | 'filtered';
+interface TierMeta {
+    label: string | null;
+    description: string;
+    shownOnPublicProfile: boolean;
+}
+interface LexiconEntry {
+    tier: ActivityTier;
+    app?: string;
+    notes?: string;
+}
+interface ActivityTaxonomy {
+    version: string;
+    updated: string;
+    tiers: Record<ActivityTier, TierMeta>;
+    lexicons: Record<string, LexiconEntry>;
+}
+declare const ACTIVITY_TIERS: Readonly<ActivityTaxonomy>;
+/**
+ * Returns the activity tier for a given AT Protocol NSID.
+ * Returns 'filtered' for unknown/unclassified NSIDs (safe default — won't
+ * leak unknown records to public profile surfaces).
+ */
+declare function getActivityTier(nsid: string): ActivityTier;
+/**
+ * Returns the full lexicon entry (tier + app + notes), or null if unknown.
+ */
+declare function getLexiconEntry(nsid: string): LexiconEntry | null;
+/**
+ * Returns tier metadata (label, description, public visibility).
+ */
+declare function getTierMeta(tier: ActivityTier): TierMeta;
+/**
+ * Returns the taxonomy version + updated date for diagnostics and
+ * version-skew detection between SDK consumers and the canonical taxonomy.
+ */
+declare function getActivityTaxonomyVersion(): {
+    version: string;
+    updated: string;
+};
+
 /**
  * Format a date string as a relative time (e.g. "5m ago", "3d ago").
  * Returns an empty string for invalid or future dates.
@@ -259,6 +304,27 @@ declare function getDisplayLabel(displayName: string | undefined, handle: string
 declare function getPdsDisplayName(providerName: string): string;
 declare function detectPdsProvider(handle: string): PdsProvider | null;
 
+/**
+ * Limit runs of Unicode combining marks (`\p{M}`) to at most `maxPerBase`
+ * marks following any single base character. Defuses "Zalgo" text where
+ * dozens of stacked combining marks render outside the line box and bleed
+ * into neighbouring UI.
+ *
+ * `maxPerBase` defaults to 4 — high enough to preserve legitimate stacks
+ * in Thai, Arabic, Vietnamese, and IPA, low enough to neutralise the
+ * vertical-overflow attack vector.
+ */
+declare function limitCombiningMarks(value: string, maxPerBase?: number): string;
+/**
+ * Sanitise untrusted display text from PDS records before rendering in UI:
+ * - strips bidi formatting controls (LRM/RLM/LRE/RLE/PDF/LRO/RLO/LRI/RLI/FSI/PDI)
+ *   that can hijack reading order or crash `next/og` (see Satori LRM+emoji bug)
+ * - limits stacked combining marks (Zalgo defence)
+ *
+ * Preserves ZWJ (U+200D) so emoji sequences keep rendering.
+ */
+declare function sanitizeDisplayText(value: string, maxCombiningPerBase?: number): string;
+
 /**
  * Truncate a string to at most `maxLen` grapheme clusters, appending an
  * ellipsis when the string was shortened. Grapheme-aware so it never splits
@@ -306,6 +372,79 @@ declare function contrastRatio(color1: RgbColor, color2: RgbColor): number;
  */
 declare function meetsContrastAA(foreground: RgbColor, background: RgbColor): boolean;
 
+/**
+ * URL patterns per app, mirroring the sifa-web registry.
+ *
+ * These describe how to build a clickable URL for an activity card given
+ * the author's handle/did and the record rkey. The patterns are templates
+ * with `{handle}`, `{did}`, and `{rkey}` placeholders; each variable is
+ * URI-encoded when interpolated.
+ *
+ * Tier semantics:
+ * - `urlPattern`: per-item URL (a specific post/event/repo). Preferred.
+ * - `profileUrlPattern`: per-user profile URL on the app. Fallback.
+ *
+ * Apps without either pattern are not clickable.
+ */
+interface AppUrlPatterns {
+    urlPattern?: string;
+    profileUrlPattern?: string;
+}
+declare const APP_URL_PATTERNS: Readonly<Record<string, AppUrlPatterns>>;
+/**
+ * Map collection NSID prefixes to app ids. Order matters: longer / more
+ * specific prefixes must come before broader ones.
+ */
+declare const COLLECTION_TO_APP: ReadonlyArray<readonly [prefix: string, appId: string]>;
+
+/**
+ * An activity item as consumed by the Sifa activity-card components and
+ * the sifa-api external-URL health scanner. The shape mirrors the props
+ * the cards already use, so the resolver returns the same URL the UI
+ * renders.
+ */
+interface ActivityItemForUrl {
+    /** Collection NSID, e.g. "sh.tangled.graph.repo". */
+    collection: string;
+    /** The raw record from the PDS / API. */
+    record: Record<string, unknown>;
+    /** Full at-uri of the record (used by collections that derive URL from uri). */
+    uri: string;
+    /** Record key. */
+    rkey: string;
+    /** DID of the author of the record. */
+    authorDid: string;
+    /** Optional handle (cards prefer handle in URL paths when available). */
+    authorHandle?: string;
+}
+/**
+ * Map a collection NSID to its app id, mirroring the sifa-web prefix map.
+ *
+ * Falls back to the first two NSID segments (e.g. "org.hyperboards") when
+ * the prefix is not registered, matching the existing card behaviour.
+ */
+declare function getAppIdForCollection(collection: string): string;
+/**
+ * Resolve the canonical clickable URL for an activity item — the same URL
+ * the activity-card UI in sifa-web renders.
+ *
+ * Returns `null` when no link is appropriate (the card would render
+ * non-clickable, or hide itself entirely).
+ *
+ * Used by:
+ * - sifa-web activity cards (single source of truth for href)
+ * - sifa-api external-URL health scanner (must match what the UI links to,
+ *   so broken-link detection lines up with what users actually click)
+ *
+ * Resolution order:
+ * 1. Per-collection bespoke logic (tangled, kipclip, margin, smokesignal
+ *    rsvp, standard documents). These mirror the inline logic in the
+ *    individual card components.
+ * 2. Generic `record.url` field (used by hyperboards and similar).
+ * 3. Pattern-based per-item / profile URL from the registry.
+ */
+declare function resolveCardUrl(item: ActivityItemForUrl): string | null;
+
 /**
  * Profile completeness scoring.
  *
@@ -393,4 +532,4 @@ declare function countFilledDimensions(input: ProfileDimensionInputs | Profile):
  */
 declare const SIFA_SDK_VERSION: string;
 
-export { CATEGORY_LABELS, CATEGORY_ORDER, COMPLETENESS_MAX_SCORE, CONTINENTS, COUNTRIES, type ContinentCode, DIMENSIONS_MAX_SCORE, type DimensionKey, type DimensionMap, EMPLOYMENT_TYPE_GROUPS, EMPLOYMENT_TYPE_LABELS, type EmploymentTypeGroup, type EmploymentTypeOption, INDUSTRY_OPTIONS, type IndustryOption, LocationValue, MIN_SKILLS, type MergedProfileSkill, OPEN_TO_OPTIONS, type OpenToOption, PLATFORM_LABELS, PLATFORM_OPTIONS, type PdsProvider, PdsProviderInfo, type PlatformId, Profile, type ProfileCompletion, type ProfileDimensionInputs, ProfileSkill, type RgbColor, SIFA_SDK_VERSION, SKILL_CATEGORIES, type SkillCategory, WORKPLACE_TYPE_LABELS, WORKPLACE_TYPE_OPTIONS, type WorkplaceTypeOption, certDateExtractor, completenessPercent, completenessScore, contrastRatio, countFilledDimensions, countryCodeToFlag, dateRangeExtractor, dedupeSkills, detectPdsProvider, dimensionsFromInputs, findIndustry, formatDistanceToNow, formatLocation, formatRelativeTime, getContinent, getDisplayLabel, getEmploymentTypeLabel, getFaviconUrl, getFilledDimensionsMap, getHandleStem, getIndustryLabelKey, getOpenToLabelKey, getPdsDisplayName, getPlatformLabel, getWorkplaceTypeLabel, groupSkillsByCategory, isKnownPlatform, isValidRgbColor, lexiconDateExtractor, meetsContrastAA, parseLocationString, pdsProviderFromApi, profileToDimensionInputs, relativeLuminance, rgbToString, sanitizeHandleInput, singleDateExtractor, sortByDateDesc, truncateGraphemes };
+export { ACTIVITY_TIERS, APP_URL_PATTERNS, type ActivityItemForUrl, type ActivityTaxonomy, type ActivityTier, type AppUrlPatterns, CATEGORY_LABELS, CATEGORY_ORDER, COLLECTION_TO_APP, COMPLETENESS_MAX_SCORE, CONTINENTS, COUNTRIES, type ContinentCode, DIMENSIONS_MAX_SCORE, type DimensionKey, type DimensionMap, EMPLOYMENT_TYPE_GROUPS, EMPLOYMENT_TYPE_LABELS, type EmploymentTypeGroup, type EmploymentTypeOption, INDUSTRY_OPTIONS, type IndustryOption, type LexiconEntry, LocationValue, MIN_SKILLS, type MergedProfileSkill, OPEN_TO_OPTIONS, type OpenToOption, PLATFORM_LABELS, PLATFORM_OPTIONS, type PdsProvider, PdsProviderInfo, type PlatformId, Profile, type ProfileCompletion, type ProfileDimensionInputs, ProfileSkill, type RgbColor, SIFA_SDK_VERSION, SKILL_CATEGORIES, type SkillCategory, type TierMeta, WORKPLACE_TYPE_LABELS, WORKPLACE_TYPE_OPTIONS, type WorkplaceTypeOption, certDateExtractor, completenessPercent, completenessScore, contrastRatio, countFilledDimensions, countryCodeToFlag, dateRangeExtractor, dedupeSkills, detectPdsProvider, dimensionsFromInputs, findIndustry, formatDistanceToNow, formatLocation, formatRelativeTime, getActivityTaxonomyVersion, getActivityTier, getAppIdForCollection, getContinent, getDisplayLabel, getEmploymentTypeLabel, getFaviconUrl, getFilledDimensionsMap, getHandleStem, getIndustryLabelKey, getLexiconEntry, getOpenToLabelKey, getPdsDisplayName, getPlatformLabel, getTierMeta, getWorkplaceTypeLabel, groupSkillsByCategory, isKnownPlatform, isValidRgbColor, lexiconDateExtractor, limitCombiningMarks, meetsContrastAA, parseLocationString, pdsProviderFromApi, profileToDimensionInputs, relativeLuminance, resolveCardUrl, rgbToString, sanitizeDisplayText, sanitizeHandleInput, singleDateExtractor, sortByDateDesc, truncateGraphemes };