@singi-labs/sifa-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,495 @@
+interface LocationValue {
+    city?: string;
+    region?: string;
+    country: string;
+    countryCode?: string;
+    postalCode?: string;
+    geonameId?: number;
+}
+interface SkillRef {
+    uri: string;
+}
+interface ProfilePosition {
+    rkey: string;
+    company: string;
+    title: string;
+    description?: string;
+    startedAt: string;
+    endedAt?: string;
+    location?: LocationValue | null;
+    workplaceType?: string;
+    skills?: SkillRef[];
+    linkedSkills?: ProfileSkill[];
+    primary?: boolean;
+}
+interface ProfileEducation {
+    rkey: string;
+    institution: string;
+    degree?: string;
+    fieldOfStudy?: string;
+    description?: string;
+    activities?: string;
+    startedAt?: string;
+    endedAt?: string;
+}
+interface ProfileSkill {
+    rkey: string;
+    name: string;
+    category?: string;
+    endorsementCount?: number;
+    endorsed?: boolean;
+    activityBacked?: boolean;
+}
+interface SkillSuggestion {
+    canonicalName: string;
+    slug: string;
+    category: string;
+}
+interface Endorsement {
+    endorserDid: string;
+    endorserHandle: string;
+    endorserDisplayName?: string;
+    endorserAvatar?: string;
+    comment?: string;
+    relationshipContext?: string;
+    createdAt: string;
+}
+interface EndorsementData {
+    skillRkey: string;
+    comment?: string;
+    relationshipContext?: string;
+}
+interface ProfileLocation {
+    rkey: string;
+    type: string;
+    label?: string | null;
+    isPrimary: boolean;
+    locationCountry?: string | null;
+    locationRegion?: string | null;
+    locationCity?: string | null;
+    countryCode?: string | null;
+    location?: string | null;
+}
+interface ProfileCertification {
+    rkey: string;
+    name: string;
+    issuingOrg: string;
+    issueDate?: string;
+    expiryDate?: string;
+    credentialUrl?: string;
+}
+interface ProfileProject {
+    rkey: string;
+    name: string;
+    description?: string;
+    url?: string;
+    startDate?: string;
+    endDate?: string;
+}
+interface PublicationContributor {
+    name: string;
+    orcidId?: string;
+    did?: string;
+    handle?: string;
+}
+interface ProfilePublication {
+    rkey: string;
+    title: string;
+    publisher?: string;
+    date?: string;
+    url?: string;
+    description?: string;
+    source?: 'sifa' | 'standard' | 'orcid';
+    doi?: string;
+    type?: string;
+    typeLabel?: string;
+    contributors?: PublicationContributor[];
+    verified?: boolean;
+    verifiedVia?: string;
+    orcidPutCode?: number;
+    hidden?: boolean;
+    orcidCorroborated?: boolean;
+    pendingVerification?: boolean;
+    appId?: string;
+}
+interface ProfileVolunteering {
+    rkey: string;
+    organization: string;
+    role?: string;
+    cause?: string;
+    startDate?: string;
+    endDate?: string;
+    description?: string;
+}
+interface ProfileHonor {
+    rkey: string;
+    title: string;
+    issuer?: string;
+    date?: string;
+    description?: string;
+}
+type LanguageProficiency = 'elementary' | 'limited_working' | 'professional_working' | 'full_professional' | 'native';
+interface ProfileLanguage {
+    rkey: string;
+    language: string;
+    proficiency?: LanguageProficiency;
+}
+interface ProfileCourse {
+    rkey: string;
+    name: string;
+    institution?: string;
+    number?: string;
+}
+interface TrustStat {
+    key: string;
+    label: string;
+    value: number;
+}
+interface ActiveApp {
+    id: string;
+    name: string;
+    category: string;
+    recentCount: number;
+    latestRecordAt?: string | null;
+}
+interface VerifiedAccount {
+    platform: string;
+    identifier: string;
+    url?: string;
+}
+interface ExternalAccountKeytraceClaim {
+    rkey: string;
+    claimedAt: string;
+}
+interface ExternalAccount {
+    rkey: string;
+    platform: string;
+    url: string;
+    label?: string;
+    feedUrl?: string;
+    primary?: boolean;
+    verifiable: boolean;
+    verified: boolean;
+    verifiedVia?: string | null;
+    source?: 'sifa' | 'keytrace' | 'keyoxide';
+    hidden?: boolean;
+    keytraceVerified?: boolean;
+    keytraceClaim?: ExternalAccountKeytraceClaim;
+}
+interface FeedItem {
+    title: string;
+    excerpt: string;
+    url: string;
+    timestamp: string;
+    source: string;
+}
+interface PdsProviderInfo {
+    name: string;
+    host: string;
+}
+interface ProfileIndustry {
+    industry: string;
+    domain?: string;
+}
+interface ProfileOverrideSource {
+    headline?: string;
+    about?: string;
+    displayName?: string;
+    avatarUrl?: string;
+}
+interface Profile {
+    did: string;
+    handle: string;
+    displayName?: string;
+    avatar?: string;
+    pronouns?: string;
+    headline?: string;
+    about?: string;
+    hasHeadlineOverride?: boolean;
+    hasAboutOverride?: boolean;
+    hasDisplayNameOverride?: boolean;
+    hasAvatarUrlOverride?: boolean;
+    source?: ProfileOverrideSource;
+    industries?: ProfileIndustry[];
+    location?: LocationValue | null;
+    locations?: ProfileLocation[];
+    website?: string;
+    openTo?: string[];
+    preferredWorkplace?: string[];
+    availableFromUtc?: number;
+    availableToUtc?: number;
+    pdsProvider?: PdsProviderInfo | null;
+    claimed: boolean;
+    isOwnProfile?: boolean;
+    createdAt?: string;
+    trustStats?: TrustStat[];
+    verifiedAccounts?: VerifiedAccount[];
+    activeApps?: ActiveApp[];
+    blueskyVerified?: boolean;
+    blueskyVerifiedAt?: string | null;
+    followersCount: number;
+    followingCount: number;
+    connectionsCount: number;
+    atprotoFollowersCount?: number;
+    positions: ProfilePosition[];
+    education: ProfileEducation[];
+    skills: ProfileSkill[];
+    certifications?: ProfileCertification[];
+    projects?: ProfileProject[];
+    publications?: ProfilePublication[];
+    volunteering?: ProfileVolunteering[];
+    honors?: ProfileHonor[];
+    languages?: ProfileLanguage[];
+    courses?: ProfileCourse[];
+    externalAccounts?: ExternalAccount[];
+}
+
+type ContinentCode = 'AF' | 'AN' | 'AS' | 'EU' | 'NA' | 'OC' | 'SA';
+declare const CONTINENTS: ReadonlyArray<{
+    code: ContinentCode;
+    name: string;
+}>;
+declare function getContinent(countryCode: string): ContinentCode | null;
+
+/** ISO 3166-1 country list for local fallback when GeoNames is unavailable. */
+declare const COUNTRIES: ReadonlyArray<{
+    code: string;
+    name: string;
+}>;
+
+/** Two-level industry/domain taxonomy for profile classification. */
+interface IndustryOption {
+    value: string;
+    labelKey: string;
+    domains: {
+        value: string;
+        labelKey: string;
+    }[];
+}
+declare const INDUSTRY_OPTIONS: IndustryOption[];
+
+/**
+ * Platform identifiers, labels, and URL helpers used in profile external accounts.
+ *
+ * This file is intentionally data-only -- icon mapping is platform-specific
+ * (React DOM components on web, React Native components on mobile) and lives
+ * in the consumer.
+ */
+declare const PLATFORM_LABELS: {
+    readonly bluesky: "Bluesky";
+    readonly github: "GitHub";
+    readonly linkedin: "LinkedIn";
+    readonly youtube: "YouTube";
+    readonly twitter: "X (Twitter)";
+    readonly instagram: "Instagram";
+    readonly substack: "Substack";
+    readonly tangled: "Tangled";
+    readonly dns: "Domain";
+    readonly website: "Website";
+    readonly rss: "RSS";
+    readonly fediverse: "Fediverse";
+    readonly orcid: "ORCID";
+    readonly keyoxide: "Keyoxide";
+};
+type PlatformId = keyof typeof PLATFORM_LABELS;
+declare function isKnownPlatform(platform: string): platform is PlatformId;
+declare function getPlatformLabel(platform: string): string;
+/** Platforms available in the "Add Links" dropdown. */
+declare const PLATFORM_OPTIONS: ReadonlyArray<{
+    value: PlatformId;
+    label: string;
+}>;
+/**
+ * Build a favicon URL for a given site URL using Google's public favicon service.
+ * Returns `null` if the URL cannot be parsed.
+ */
+declare function getFaviconUrl(siteUrl: string): string | null;
+
+declare const SKILL_CATEGORIES: readonly [{
+    readonly value: "technical";
+    readonly label: "Technical";
+}, {
+    readonly value: "business";
+    readonly label: "Business";
+}, {
+    readonly value: "creative";
+    readonly label: "Creative";
+}, {
+    readonly value: "interpersonal";
+    readonly label: "Interpersonal";
+}, {
+    readonly value: "industry";
+    readonly label: "Industry";
+}, {
+    readonly value: "community";
+    readonly label: "Community";
+}, {
+    readonly value: "security";
+    readonly label: "Security";
+}];
+type SkillCategory = (typeof SKILL_CATEGORIES)[number]['value'];
+declare const CATEGORY_ORDER: ReadonlyArray<SkillCategory>;
+declare const CATEGORY_LABELS: Record<SkillCategory | 'other', string>;
+
+type MergedProfileSkill = ProfileSkill & {
+    mergedRkeys: string[];
+    positionRkeys?: string[];
+};
+/**
+ * Collapses skills that resolve to the same name (case-insensitive, trimmed).
+ *
+ * LinkedIn import creates one skill record per (skill, position) pair, so a
+ * profile can have several "Ruby" rows. We surface them as a single chip with
+ * all underlying rkeys exposed via `mergedRkeys` so edit/delete can fan out.
+ */
+declare function dedupeSkills(skills: ProfileSkill[]): MergedProfileSkill[];
+/**
+ * Groups skills by category in CATEGORY_ORDER, with unknown/empty categories
+ * collected under "other". Within each group: sorted by endorsementCount desc,
+ * then alphabetical by name. Empty groups are omitted.
+ */
+declare function groupSkillsByCategory<T extends ProfileSkill>(skills: T[]): [string, T[]][];
+
+/**
+ * Format a date string as a relative time (e.g. "5m ago", "3d ago").
+ * Returns an empty string for invalid or future dates.
+ */
+declare function formatRelativeTime(dateString: string): string;
+
+/**
+ * Sort profile section items from newest to oldest.
+ *
+ * Rules:
+ * - Items with no end date (ongoing/current) sort to the top.
+ * - Primary sort: end date descending (newest first).
+ * - Secondary sort: start date descending (newest first).
+ * - Items with no dates sort to the bottom.
+ *
+ * Date strings are ISO-ish ("2024", "2024-03", "2024-03-15") and
+ * lexicographic comparison works correctly for them.
+ */
+interface DateRange {
+    startDate?: string;
+    endDate?: string;
+    current?: boolean;
+}
+type DateExtractor<T> = (item: T) => DateRange;
+declare function sortByDateDesc<T>(items: T[], extract: DateExtractor<T>): T[];
+/**
+ * Convenience extractor for items that use `startDate` / `endDate` fields directly.
+ * Used by volunteering, projects, and other sections that still use startDate/endDate.
+ */
+declare function dateRangeExtractor<T extends {
+    startDate?: string;
+    endDate?: string;
+    current?: boolean;
+}>(item: T): DateRange;
+/**
+ * Extractor for lexicon-aligned items that use `startedAt` / `endedAt` fields.
+ * Used by positions and education (current derived from !endedAt).
+ */
+declare function lexiconDateExtractor<T extends {
+    startedAt?: string;
+    endedAt?: string;
+}>(item: T): DateRange;
+/**
+ * Convenience extractor for items with a single `date` field.
+ */
+declare function singleDateExtractor<T extends {
+    date?: string;
+}>(item: T): DateRange;
+/**
+ * Extractor for certifications which use `issueDate` / `expiryDate`.
+ */
+declare function certDateExtractor<T extends {
+    issueDate?: string;
+    expiryDate?: string;
+}>(item: T): DateRange;
+
+/**
+ * Sanitize raw user input into a valid AT Protocol identifier (handle or DID).
+ *
+ * Handles common mistakes:
+ * - Pasting a full Bluesky profile URL
+ * - Pasting a raw HTTPS URL to a PDS domain
+ * - Using an at:// URI
+ * - Prefixing with @
+ * - Entering a bare username without .bsky.social
+ */
+declare function sanitizeHandleInput(raw: string): string;
+
+/** Format a LocationValue for display */
+declare function formatLocation(loc: LocationValue | null | undefined): string;
+/** Parse a display string back into a LocationValue (best-effort for legacy data) */
+declare function parseLocationString(str: string): LocationValue | null;
+/** Convert ISO 3166-1 alpha-2 country code to flag emoji */
+declare function countryCodeToFlag(code: string | undefined): string;
+
+interface PdsProvider {
+    name: string;
+    profileUrl: string;
+    host?: string;
+}
+declare function pdsProviderFromApi(apiProvider: PdsProviderInfo | null | undefined, handle: string): PdsProvider | null;
+declare function getHandleStem(handle: string): string;
+declare function getDisplayLabel(displayName: string | undefined, handle: string): string;
+declare function getPdsDisplayName(providerName: string): string;
+declare function detectPdsProvider(handle: string): PdsProvider | null;
+
+/**
+ * Truncate a string to at most `maxLen` grapheme clusters, appending an
+ * ellipsis when the string was shortened. Grapheme-aware so it never splits
+ * emoji sequences (ZWJ, regional indicators, combining marks, surrogate pairs).
+ */
+declare function truncateGraphemes(value: string, maxLen: number): string;
+
+/**
+ * Format a date as a relative time string (e.g. "2 minutes ago", "3 days ago").
+ */
+declare function formatDistanceToNow(date: Date): string;
+
+/**
+ * WCAG 2.2 contrast ratio utilities for validating publication theme colors.
+ * Implements the relative luminance and contrast ratio formulas from
+ * https://www.w3.org/TR/WCAG22/#dfn-relative-luminance
+ */
+interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Return true when the value is an RgbColor with all channels as integers in [0, 255].
+ * Use this before passing untrusted data to the luminance / contrast functions.
+ */
+declare function isValidRgbColor(value: unknown): value is RgbColor;
+/**
+ * Serialize an RgbColor to a CSS `rgb(...)` string.
+ * Channels are floored to integers to prevent sub-pixel drift.
+ */
+declare function rgbToString(color: RgbColor): string;
+/**
+ * Calculate relative luminance of an sRGB color per WCAG 2.2.
+ * Input channels must be numbers in [0, 255].
+ */
+declare function relativeLuminance(color: RgbColor): number;
+/**
+ * Calculate WCAG 2.2 contrast ratio between two colors.
+ * Returns a value between 1 (identical) and 21 (black/white).
+ */
+declare function contrastRatio(color1: RgbColor, color2: RgbColor): number;
+/**
+ * Check if two colors meet WCAG 2.2 AA contrast requirement (4.5:1 for normal text).
+ */
+declare function meetsContrastAA(foreground: RgbColor, background: RgbColor): boolean;
+
+/**
+ * Sifa SDK -- public client library for the Sifa AppView on AT Protocol.
+ *
+ * Pre-1.0: the public API is unstable and may change in any minor release.
+ *
+ * @see https://github.com/singi-labs/sifa-sdk
+ */
+declare const SIFA_SDK_VERSION: string;
+
+export { type ActiveApp, CATEGORY_LABELS, CATEGORY_ORDER, CONTINENTS, COUNTRIES, type ContinentCode, type Endorsement, type EndorsementData, type ExternalAccount, type ExternalAccountKeytraceClaim, type FeedItem, INDUSTRY_OPTIONS, type IndustryOption, type LanguageProficiency, type LocationValue, type MergedProfileSkill, PLATFORM_LABELS, PLATFORM_OPTIONS, type PdsProvider, type PdsProviderInfo, type PlatformId, type Profile, type ProfileCertification, type ProfileCourse, type ProfileEducation, type ProfileHonor, type ProfileIndustry, type ProfileLanguage, type ProfileLocation, type ProfileOverrideSource, type ProfilePosition, type ProfileProject, type ProfilePublication, type ProfileSkill, type ProfileVolunteering, type PublicationContributor, type RgbColor, SIFA_SDK_VERSION, SKILL_CATEGORIES, type SkillCategory, type SkillRef, type SkillSuggestion, type TrustStat, type VerifiedAccount, certDateExtractor, contrastRatio, countryCodeToFlag, dateRangeExtractor, dedupeSkills, detectPdsProvider, formatDistanceToNow, formatLocation, formatRelativeTime, getContinent, getDisplayLabel, getFaviconUrl, getHandleStem, getPdsDisplayName, getPlatformLabel, groupSkillsByCategory, isKnownPlatform, isValidRgbColor, lexiconDateExtractor, meetsContrastAA, parseLocationString, pdsProviderFromApi, relativeLuminance, rgbToString, sanitizeHandleInput, singleDateExtractor, sortByDateDesc, truncateGraphemes };