@singi-labs/sifa-sdk 0.5.0 → 0.7.0

package/dist/query/index.d.ts

@@ -0,0 +1,378 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { P as Profile } from '../index-IDRpze8y.js';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { UseQueryOptions, UseMutationOptions } from '@tanstack/react-query';
+
+/**
+ * Foundation HTTP client for talking to the Sifa AppView.
+ *
+ * Stateless. Consumers supply a {@link SifaApiConfig} per call (the React
+ * hooks read it from context; non-React consumers pass it explicitly). No
+ * singletons, no module-level state.
+ */
+/** Configuration passed to every fetcher. */
+interface SifaApiConfig {
+    /** Base URL of the sifa-api AppView, e.g. `https://api.sifa.id`. No trailing slash. */
+    baseUrl: string;
+    /**
+     * Optional fetch implementation. Defaults to {@link globalThis.fetch}.
+     * Lets Next.js consumers pass their cache-enhanced fetch; node/Expo
+     * consumers can leave this unset.
+     */
+    fetch?: typeof fetch;
+}
+/** Options accepted by {@link apiFetch}. */
+interface ApiFetchOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Request body. Serialized to JSON automatically. */
+    body?: unknown;
+    /** AbortSignal. Defaults to `AbortSignal.timeout(timeoutMs)` if `timeoutMs` is set. */
+    signal?: AbortSignal;
+    /** Per-call timeout in milliseconds. Default: 10_000. Ignored if `signal` is provided. */
+    timeoutMs?: number;
+    /** Retry on HTTP 429 up to 3 times with the server's `Retry-After` delay (capped at 3s). */
+    retryOn429?: boolean;
+    /** Additional headers. `Content-Type: application/json` is set automatically when `body` is present. */
+    headers?: Record<string, string>;
+    credentials?: RequestCredentials;
+    cache?: RequestCache;
+    /**
+     * Next.js-specific cache hints. Ignored on non-Next runtimes. Passed
+     * through transparently as part of {@link RequestInit}.
+     */
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+}
+/** Error thrown by {@link apiFetch} on non-2xx responses. */
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+/**
+ * Generic fetcher used by all SDK query and mutation functions.
+ *
+ * Returns parsed JSON typed as `T`. Throws {@link ApiError} on non-2xx
+ * responses. Use {@link apiFetchOrNull} when 404 should resolve to `null`
+ * instead.
+ */
+declare function apiFetch<T = unknown>(config: SifaApiConfig, path: string, options?: ApiFetchOptions): Promise<T>;
+/**
+ * Variant of {@link apiFetch} that resolves to `null` on HTTP 404 instead
+ * of throwing. Useful for "fetch by handle" reads where missing is
+ * expected (e.g. unknown profile).
+ */
+declare function apiFetchOrNull<T>(config: SifaApiConfig, path: string, options?: ApiFetchOptions): Promise<T | null>;
+
+interface SifaProviderProps {
+    config: SifaApiConfig;
+    children: ReactNode;
+}
+/**
+ * Provides the {@link SifaApiConfig} that hooks under it can read via
+ * {@link useSifaConfig}. Wrap the React tree once; hooks consume it.
+ *
+ * @example
+ * ```tsx
+ * <QueryClientProvider client={queryClient}>
+ *   <SifaProvider config={{ baseUrl: process.env.NEXT_PUBLIC_API_URL! }}>
+ *     <App />
+ *   </SifaProvider>
+ * </QueryClientProvider>
+ * ```
+ */
+declare function SifaProvider({ config, children }: SifaProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Read the SDK's {@link SifaApiConfig} from context. Throws if no
+ * {@link SifaProvider} is mounted above.
+ */
+declare function useSifaConfig(): SifaApiConfig;
+
+/**
+ * Read the aggregated profile for a handle or DID.
+ *
+ * Returns `null` when the AppView has no profile for the given identifier
+ * (HTTP 404). Throws {@link ApiError} on other non-2xx responses.
+ *
+ * Server-callable (Next.js RSC) and client-callable (Expo, browser).
+ */
+declare function fetchProfile(config: SifaApiConfig, handleOrDid: string, options?: ApiFetchOptions): Promise<Profile | null>;
+
+/** Result returned by record-write mutations (create / update / delete). */
+interface WriteResult {
+    success: boolean;
+    error?: string;
+    pdsHost?: string;
+}
+/** Result returned by create mutations. Includes the newly created `rkey`. */
+interface CreateResult extends WriteResult {
+    rkey?: string;
+}
+/**
+ * Create a new `id.sifa.profile.position` record on the authenticated
+ * user's PDS. The AppView signs and writes via the user's OAuth session.
+ *
+ * `data` should be a lexicon-shaped position record (without `createdAt`
+ * or `rkey`; the AppView fills both). Validate with
+ * `ProfilePositionRecordSchema.omit({ createdAt: true })` before calling
+ * if you want client-side guarantees.
+ */
+declare function createPosition(config: SifaApiConfig, data: Record<string, unknown>, options?: ApiFetchOptions): Promise<CreateResult>;
+
+/** Profile entry returned by the search endpoint. */
+interface ProfileSearchResult {
+    did?: string;
+    handle: string;
+    displayName?: string;
+    headline?: string;
+    avatar?: string;
+    about?: string;
+    currentRole?: string;
+    currentCompany?: string;
+    industry?: string;
+    domain?: string;
+    countryCode?: string;
+    locationCountry?: string;
+    preferredWorkplace?: string[];
+    claimed?: boolean;
+    blueskyVerified?: boolean;
+    blueskyVerifiedAt?: string | null;
+}
+interface SearchFilters {
+    q?: string;
+    skill?: string;
+    country?: string;
+    industry?: string;
+    domain?: string;
+    workplace?: string;
+    app?: string;
+    limit?: number;
+}
+interface SearchResponse {
+    profiles: ProfileSearchResult[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/** Skill typeahead suggestion. */
+interface SkillSearchResult {
+    name: string;
+    slug: string;
+    category: string;
+    userCount: number;
+}
+interface FilterOptions {
+    countries: {
+        countryCode: string;
+        country: string;
+        count: number;
+    }[];
+    industries: {
+        industry: string;
+        count: number;
+    }[];
+    apps: {
+        appId: string;
+        count: number;
+    }[];
+}
+/**
+ * Search profiles by free-text query and optional filters. Returns an
+ * empty result set when no filters are provided (matching sifa-web's
+ * "no input, no fetch" behavior).
+ */
+declare function fetchSearchProfiles(config: SifaApiConfig, filters: SearchFilters, options?: ApiFetchOptions): Promise<SearchResponse>;
+/**
+ * Skill typeahead. Returns up to 8 matches for the given prefix. Empty
+ * input returns an empty array without hitting the server.
+ */
+declare function fetchSkillSuggestions(config: SifaApiConfig, query: string, options?: ApiFetchOptions): Promise<SkillSearchResult[]>;
+/** Available filter facets (countries, industries, apps) for search UI. */
+declare function fetchSearchFilters(config: SifaApiConfig, options?: ApiFetchOptions): Promise<FilterOptions>;
+
+/** Lightweight profile representation used by discovery endpoints. */
+interface SimilarProfile {
+    did: string;
+    handle: string;
+    displayName?: string | null;
+    avatar?: string | null;
+    headline?: string | null;
+    currentRole?: string | null;
+    currentCompany?: string | null;
+    industry?: string | null;
+    domain?: string | null;
+}
+interface SuggestionProfile {
+    did: string;
+    handle: string;
+    displayName?: string;
+    headline?: string;
+    avatarUrl?: string;
+    source: string;
+    dismissed: boolean;
+    blueskyVerified?: boolean;
+}
+interface SuggestionsResponse {
+    onSifa: SuggestionProfile[];
+    notOnSifa: SuggestionProfile[];
+    cursor?: string;
+}
+interface FeaturedProfile {
+    did: string;
+    handle: string;
+    displayName?: string;
+    avatar?: string;
+    pronouns?: string;
+    headline?: string;
+    about?: string;
+    currentRole?: string;
+    currentCompany?: string;
+    locationCountry?: string;
+    locationRegion?: string;
+    /** Legacy alias for `locationLocality`; emitted by sifa-api during the additive response window. */
+    locationCity?: string;
+    /** community.lexicon.location.address field name -- prefer over `locationCity`. */
+    locationLocality?: string;
+    countryCode?: string;
+    location?: string;
+    website?: string;
+    openTo?: string[];
+    preferredWorkplace?: string[];
+    availableFromUtc?: number;
+    availableToUtc?: number;
+    followersCount?: number;
+    atprotoFollowersCount?: number;
+    pdsProvider?: {
+        name: string;
+        host: string;
+    } | null;
+    claimed: boolean;
+    featuredDate: string;
+}
+/** Profiles similar to the given DID (matchmaking). Returns `[]` on error. */
+declare function fetchSimilarProfiles(config: SifaApiConfig, did: string, opts?: {
+    limit?: number;
+} & ApiFetchOptions): Promise<SimilarProfile[]>;
+interface FetchSuggestionsOptions extends ApiFetchOptions {
+    source?: string;
+    includeDismissed?: boolean;
+    cursor?: string;
+    limit?: number;
+    /**
+     * Pass the caller's `Cookie` header on Next.js RSC server-side calls.
+     * `credentials: 'include'` does NOT propagate browser cookies in RSC,
+     * so authenticated server fetches must forward the header explicitly.
+     */
+    cookieHeader?: string;
+}
+/** Discovery suggestions feed. Resolves to empty arrays on error. */
+declare function fetchSuggestions(config: SifaApiConfig, opts?: FetchSuggestionsOptions): Promise<SuggestionsResponse>;
+/** Count of pending suggestions since an optional timestamp. */
+declare function fetchSuggestionCount(config: SifaApiConfig, since?: string, options?: ApiFetchOptions): Promise<number>;
+/** Featured profile (rotated by sifa-api). Returns `null` when none. */
+declare function fetchFeaturedProfile(config: SifaApiConfig, options?: ApiFetchOptions): Promise<FeaturedProfile | null>;
+
+interface FollowProfile {
+    did: string;
+    handle: string;
+    displayName?: string;
+    headline?: string;
+    avatarUrl?: string;
+    source: string;
+    claimed: boolean;
+    followedAt: string;
+    blueskyVerified?: boolean;
+    blueskyVerifiedAt?: string | null;
+}
+interface FollowingResponse {
+    follows: FollowProfile[];
+    cursor?: string;
+}
+/** People the authenticated user follows. Empty on error. */
+declare function fetchFollowing(config: SifaApiConfig, opts?: {
+    source?: string;
+    cursor?: string;
+    limit?: number;
+} & ApiFetchOptions): Promise<FollowingResponse>;
+
+/**
+ * Query key factory for TanStack Query.
+ *
+ * Keys are read-only tuples; the hierarchy matches the SDK's fetcher
+ * grouping. Use these instead of inline arrays so consumers can target
+ * `queryClient.invalidateQueries({ queryKey: keys.profile.all() })` and
+ * similar patterns without typos.
+ *
+ * Convention: every leaf key starts with the namespace ('sifa') so
+ * consumers can invalidate everything Sifa-related in one call.
+ */
+declare const sifaQueryKeys: {
+    readonly all: () => readonly ["sifa"];
+    readonly profile: {
+        readonly all: () => readonly ["sifa", "profile"];
+        readonly byHandle: (handleOrDid: string) => readonly ["sifa", "profile", string];
+    };
+    readonly position: {
+        readonly all: () => readonly ["sifa", "position"];
+        readonly byOwner: (did: string) => readonly ["sifa", "position", "by-owner", string];
+    };
+    readonly search: {
+        readonly all: () => readonly ["sifa", "search"];
+        readonly profiles: (filters: Record<string, unknown>) => readonly ["sifa", "search", "profiles", Record<string, unknown>];
+        readonly skills: (query: string) => readonly ["sifa", "search", "skills", string];
+        readonly filters: () => readonly ["sifa", "search", "filters"];
+    };
+    readonly discovery: {
+        readonly all: () => readonly ["sifa", "discovery"];
+        readonly similar: (did: string, limit: number) => readonly ["sifa", "discovery", "similar", string, number];
+        readonly suggestions: (opts: Record<string, unknown>) => readonly ["sifa", "discovery", "suggestions", Record<string, unknown>];
+        readonly suggestionCount: (since: string | undefined) => readonly ["sifa", "discovery", "suggestion-count", string | null];
+        readonly featured: () => readonly ["sifa", "discovery", "featured"];
+    };
+    readonly follow: {
+        readonly all: () => readonly ["sifa", "follow"];
+        readonly following: (opts: Record<string, unknown>) => readonly ["sifa", "follow", "following", Record<string, unknown>];
+    };
+};
+type SifaQueryKey = ReturnType<typeof sifaQueryKeys.all> | ReturnType<typeof sifaQueryKeys.profile.all> | ReturnType<typeof sifaQueryKeys.profile.byHandle> | ReturnType<typeof sifaQueryKeys.position.all> | ReturnType<typeof sifaQueryKeys.position.byOwner> | ReturnType<typeof sifaQueryKeys.search.all> | ReturnType<typeof sifaQueryKeys.search.profiles> | ReturnType<typeof sifaQueryKeys.search.skills> | ReturnType<typeof sifaQueryKeys.search.filters> | ReturnType<typeof sifaQueryKeys.discovery.all> | ReturnType<typeof sifaQueryKeys.discovery.similar> | ReturnType<typeof sifaQueryKeys.discovery.suggestions> | ReturnType<typeof sifaQueryKeys.discovery.suggestionCount> | ReturnType<typeof sifaQueryKeys.discovery.featured> | ReturnType<typeof sifaQueryKeys.follow.all> | ReturnType<typeof sifaQueryKeys.follow.following>;
+
+/**
+ * React hook that reads an aggregated profile by handle or DID via
+ * TanStack Query. Returns `null` data when the profile does not exist.
+ *
+ * Pass `{ enabled: false }` (or an empty `handleOrDid`) to defer the
+ * fetch.
+ */
+declare function useProfile(handleOrDid: string | undefined | null, options?: Omit<UseQueryOptions<Profile | null, Error, Profile | null, ReturnType<typeof sifaQueryKeys.profile.byHandle>>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<Profile | null, Error>;
+
+/**
+ * React hook for creating a new position record. On success, invalidates
+ * the owner's profile cache so the new position is reflected on the next
+ * read.
+ *
+ * The owner DID is required so the mutation can target the correct
+ * profile cache entry for invalidation.
+ */
+declare function useCreatePosition(ownerDid: string, options?: Omit<UseMutationOptions<CreateResult, Error, Record<string, unknown>>, 'mutationFn'>): _tanstack_react_query.UseMutationResult<CreateResult, Error, Record<string, unknown>, unknown>;
+
+declare function useSearchProfiles(filters: SearchFilters, options?: Omit<UseQueryOptions<SearchResponse, Error, SearchResponse, ReturnType<typeof sifaQueryKeys.search.profiles>>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<SearchResponse, Error>;
+declare function useSkillSuggestions(query: string, options?: Omit<UseQueryOptions<SkillSearchResult[], Error, SkillSearchResult[], ReturnType<typeof sifaQueryKeys.search.skills>>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<SkillSearchResult[], Error>;
+declare function useSearchFilters(options?: Omit<UseQueryOptions<FilterOptions, Error, FilterOptions, ReturnType<typeof sifaQueryKeys.search.filters>>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<FilterOptions, Error>;
+
+declare function useSimilarProfiles(did: string | undefined | null, opts?: {
+    limit?: number;
+}, options?: Omit<UseQueryOptions<SimilarProfile[], Error, SimilarProfile[], ReturnType<typeof sifaQueryKeys.discovery.similar>>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<SimilarProfile[], Error>;
+declare function useSuggestions(opts?: Omit<FetchSuggestionsOptions, keyof Omit<FetchSuggestionsOptions, 'source' | 'includeDismissed' | 'cursor' | 'limit'>>, options?: Omit<UseQueryOptions<SuggestionsResponse, Error, SuggestionsResponse, ReturnType<typeof sifaQueryKeys.discovery.suggestions>>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<SuggestionsResponse, Error>;
+declare function useSuggestionCount(since?: string, options?: Omit<UseQueryOptions<number, Error, number, ReturnType<typeof sifaQueryKeys.discovery.suggestionCount>>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<number, Error>;
+declare function useFeaturedProfile(options?: Omit<UseQueryOptions<FeaturedProfile | null, Error, FeaturedProfile | null, ReturnType<typeof sifaQueryKeys.discovery.featured>>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<FeaturedProfile | null, Error>;
+
+declare function useFollowing(opts?: {
+    source?: string;
+    cursor?: string;
+    limit?: number;
+}, options?: Omit<UseQueryOptions<FollowingResponse, Error, FollowingResponse, ReturnType<typeof sifaQueryKeys.follow.following>>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<FollowingResponse, Error>;
+
+export { ApiError, type ApiFetchOptions, type CreateResult, type FeaturedProfile, type FetchSuggestionsOptions, type FilterOptions, type FollowProfile, type FollowingResponse, type ProfileSearchResult, type SearchFilters, type SearchResponse, type SifaApiConfig, SifaProvider, type SifaProviderProps, type SifaQueryKey, type SimilarProfile, type SkillSearchResult, type SuggestionProfile, type SuggestionsResponse, type WriteResult, apiFetch, apiFetchOrNull, createPosition, fetchFeaturedProfile, fetchFollowing, fetchProfile, fetchSearchFilters, fetchSearchProfiles, fetchSimilarProfiles, fetchSkillSuggestions, fetchSuggestionCount, fetchSuggestions, sifaQueryKeys, useCreatePosition, useFeaturedProfile, useFollowing, useProfile, useSearchFilters, useSearchProfiles, useSifaConfig, useSimilarProfiles, useSkillSuggestions, useSuggestionCount, useSuggestions };