@singi-labs/sifa-sdk 0.11.23 → 0.11.25

package/dist/index-CCi2sg_u.d.ts

@@ -0,0 +1,261 @@
+import { S as SifaApiConfig, A as ApiFetchOptions, j as CreateResult, W as WriteResult } from './keys-CxTXTPnI.js';
+import { d as Profile, v as ProfilePosition, D as SkillRef } from './adult-content-pvNBfDQL.js';
+import { m as EntitySearchResponse, E as EntitySearchResult, g as EntityMintDomainResponse, k as EntityResolveDomainResponse, p as EntitySelectRequest, r as EntitySelectResponse } from './feed-D2ZV8Eaj.js';
+
+/**
+ * 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>;
+/**
+ * Public AT Fund link for a profile, if one is configured. Returns `null`
+ * on any error or when the response payload's `url` field is missing or
+ * non-string.
+ */
+declare function fetchAtFundLink(config: SifaApiConfig, did: string, options?: ApiFetchOptions): Promise<string | null>;
+
+/**
+ * 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.
+ *
+ * Never throws -- inspect `result.success` and use `result.error` /
+ * `result.pdsHost` for UI messaging.
+ */
+declare function createPosition(config: SifaApiConfig, data: Record<string, unknown>, options?: ApiFetchOptions): Promise<CreateResult>;
+/** Update an existing position by `rkey`. */
+declare function updatePosition(config: SifaApiConfig, rkey: string, data: Record<string, unknown>, options?: ApiFetchOptions): Promise<WriteResult>;
+/** Delete a position by `rkey`. */
+declare function deletePosition(config: SifaApiConfig, rkey: string, options?: ApiFetchOptions): Promise<WriteResult>;
+/** Mark a position as the user's primary (current) role. */
+declare function setPositionPrimary(config: SifaApiConfig, rkey: string, options?: ApiFetchOptions): Promise<WriteResult>;
+/** Clear the "primary" flag on a position. */
+declare function unsetPositionPrimary(config: SifaApiConfig, rkey: string, options?: ApiFetchOptions): Promise<WriteResult>;
+/**
+ * Add a skill link to a position. Idempotent: if the skill is already
+ * linked, resolves to `{ success: true }` without a network call.
+ *
+ * Implementation note: the AppView only exposes whole-record PUTs, so
+ * this helper rebuilds the position body with the new skills list.
+ */
+declare function linkSkillToPosition(config: SifaApiConfig, position: ProfilePosition, skillRef: SkillRef, options?: ApiFetchOptions): Promise<WriteResult>;
+/** Remove a skill link from a position. */
+declare function unlinkSkillFromPosition(config: SifaApiConfig, position: ProfilePosition, skillRef: SkillRef, options?: ApiFetchOptions): Promise<WriteResult>;
+
+/**
+ * Create a new `id.sifa.profile.education` record on the authenticated
+ * user's PDS.
+ */
+declare function createEducation(config: SifaApiConfig, data: Record<string, unknown>, options?: ApiFetchOptions): Promise<CreateResult>;
+/** Update an existing education record by `rkey`. */
+declare function updateEducation(config: SifaApiConfig, rkey: string, data: Record<string, unknown>, options?: ApiFetchOptions): Promise<WriteResult>;
+/** Delete an education record by `rkey`. */
+declare function deleteEducation(config: SifaApiConfig, rkey: string, options?: ApiFetchOptions): Promise<WriteResult>;
+
+/**
+ * Create a new `id.sifa.profile.skill` record on the authenticated
+ * user's PDS.
+ */
+declare function createSkill(config: SifaApiConfig, data: Record<string, unknown>, options?: ApiFetchOptions): Promise<CreateResult>;
+/** Update an existing skill record by `rkey`. */
+declare function updateSkill(config: SifaApiConfig, rkey: string, data: Record<string, unknown>, options?: ApiFetchOptions): Promise<WriteResult>;
+/** Delete a skill record by `rkey`. */
+declare function deleteSkill(config: SifaApiConfig, rkey: string, options?: ApiFetchOptions): Promise<WriteResult>;
+
+/**
+ * Generic record-create escape hatch. Most callers should prefer the
+ * dedicated section helpers (`createPosition`, `createEducation`, etc.)
+ * which take typed payloads and ship matching hooks. Use this when the
+ * lexicon doesn't yet have a dedicated endpoint (certifications,
+ * projects, publications, volunteering, honors, languages, courses).
+ *
+ * `collection` is a `id.sifa.profile.*` collection NSID. Routes to
+ * `POST /api/profile/records/<collection>`.
+ */
+declare function createRecord(config: SifaApiConfig, collection: string, data: Record<string, unknown>, options?: ApiFetchOptions): Promise<CreateResult>;
+/** Generic record-update escape hatch. See {@link createRecord}. */
+declare function updateRecord(config: SifaApiConfig, collection: string, rkey: string, data: Record<string, unknown>, options?: ApiFetchOptions): Promise<WriteResult>;
+/** Generic record-delete escape hatch. See {@link createRecord}. */
+declare function deleteRecord(config: SifaApiConfig, collection: string, rkey: string, options?: ApiFetchOptions): Promise<WriteResult>;
+
+/**
+ * Hide a keytrace claim (verified-account claim discovered on the
+ * user's external accounts) from the user's profile. The claim itself
+ * stays in the index; only its display is suppressed.
+ */
+declare function hideKeytraceClaim(config: SifaApiConfig, rkey: string, options?: ApiFetchOptions): Promise<WriteResult>;
+/** Restore a previously-hidden keytrace claim. */
+declare function unhideKeytraceClaim(config: SifaApiConfig, rkey: string, options?: ApiFetchOptions): Promise<WriteResult>;
+
+/**
+ * Make a Marque-registered domain public in the owner's Links section. Marque
+ * domains are owner-only by default; this reveals one. `domain` is the
+ * at.marque.domain rkey (the domain name itself).
+ */
+declare function revealMarqueDomain(config: SifaApiConfig, domain: string, options?: ApiFetchOptions): Promise<WriteResult>;
+/** Make a previously-revealed Marque domain owner-only again. */
+declare function unrevealMarqueDomain(config: SifaApiConfig, domain: string, options?: ApiFetchOptions): Promise<WriteResult>;
+
+/**
+ * Organization typeahead. Returns curated entities first, then the PDL crawl,
+ * deduped by domain. Empty input returns an empty result without a network call.
+ */
+declare function fetchEntitySearch(config: SifaApiConfig, query: string, limit?: number, options?: ApiFetchOptions): Promise<EntitySearchResponse>;
+/**
+ * Record a selection: promote a PDL row into a canonical entity (dedupe by
+ * domain) or bump an existing entity's usage counter. Returns the entity plus
+ * its portable `entityRef` (null for PDL-only entities). Requires a session.
+ */
+declare function selectEntity(config: SifaApiConfig, body: EntitySelectRequest, options?: ApiFetchOptions): Promise<EntitySelectResponse>;
+/**
+ * Grow-on-demand: when the local typeahead misses, resolve the query live via
+ * Wikidata, import the org-class matches, and return them. Requires a session.
+ * Empty input returns an empty array without a network call.
+ */
+declare function importSearchEntities(config: SifaApiConfig, query: string, options?: ApiFetchOptions): Promise<EntitySearchResult[]>;
+/**
+ * Grow-on-demand by domain, Branch 1: when a domain-shaped typeahead query
+ * misses locally, resolve any notable company whose official website is that
+ * domain (Wikidata reverse P856), importing the matches. Read-only w.r.t.
+ * minting. `canMint` tells the caller whether to offer the user-initiated
+ * "Add <domain>" affordance. Requires a session.
+ */
+declare function resolveEntityDomain(config: SifaApiConfig, domain: string, options?: ApiFetchOptions): Promise<EntityResolveDomainResponse>;
+/**
+ * Grow-on-demand by domain, Branch 2 (user-initiated): mint a crawled-tier
+ * entity from the domain's own homepage (or resolve it to a notable company if
+ * one exists). Throws on a non-2xx response (domain not mintable, or the site
+ * yielded nothing usable). Requires a session.
+ */
+declare function mintEntityDomain(config: SifaApiConfig, domain: string, options?: ApiFetchOptions): Promise<EntityMintDomainResponse>;
+
+/**
+ * Counts confirmed endorsements received by a DID. The backend's
+ * `GET /api/endorsement/:did` already returns only confirmed endorsements
+ * (via inner join with `endorsementConfirmations`), so this helper just
+ * returns the array length. Failures return 0 so callers can route safely.
+ *
+ * Public endpoint -- no credentials needed.
+ */
+declare function fetchEndorsementCount(config: SifaApiConfig, did: string, options?: ApiFetchOptions): Promise<number>;
+
+interface FetchNetworkStreamCountOptions extends ApiFetchOptions {
+    /**
+     * Pass the caller's `Cookie` header on Next.js RSC server-side calls.
+     * Required for authenticated server fetches because `credentials: 'include'`
+     * does not propagate browser cookies in RSC.
+     *
+     * When omitted, the request falls back to `credentials: 'include'` so
+     * client-side calls work without extra plumbing.
+     */
+    cookieHeader?: string;
+}
+/**
+ * Counts items in the authenticated user's network stream digest. The
+ * underlying `GET /api/stream/network` endpoint may 404 while the feature
+ * is in development; in that case (and on any other error) this returns
+ * 0 so callers can route safely to a fallback experience.
+ */
+declare function fetchNetworkStreamCount(config: SifaApiConfig, did: string, options?: FetchNetworkStreamCountOptions): Promise<number>;
+
+/** A node in the personal network graph. */
+interface NetworkMapNode {
+    did: string;
+    handle: string;
+    displayName: string;
+    avatar: string | null;
+    /** Number of edges this node participates in within the rendered graph. */
+    degree: number;
+    /** Phase 2: community detection cluster id. */
+    cluster?: number;
+    /** Phase 2: pre-computed layout coordinates. */
+    x?: number;
+    y?: number;
+}
+/** A directed edge in the personal network graph. */
+interface NetworkMapEdge {
+    source: string;
+    target: string;
+    mutual: boolean;
+    /** Networks this edge was observed in, e.g. `['sifa', 'bluesky']`. */
+    sources: string[];
+}
+/** The graph payload itself, decoupled from response metadata. */
+interface NetworkMapGraphData {
+    nodes: NetworkMapNode[];
+    edges: NetworkMapEdge[];
+    /** Phase 2: cluster metadata for legend rendering. */
+    clusters?: Array<{
+        id: number;
+        label: string;
+        color: string;
+    }>;
+}
+/** Cached graph response. */
+interface NetworkMapResponse {
+    generatedAt: string;
+    expiresAt: string;
+    graph: NetworkMapGraphData;
+    stats: {
+        totalNodes: number;
+        totalEdges: number;
+        mutualCount: number;
+        sources: Record<string, number>;
+    };
+}
+/** Async job tracking generation progress. */
+interface NetworkMapGenerationJob {
+    jobId: string;
+    did: string;
+    status: 'pending' | 'complete' | 'failed';
+    /** 0..100 */
+    progress: number;
+    createdAt: string;
+    completedAt?: string;
+    error?: string;
+    /**
+     * Queue position when the job is still pending and not yet picked up
+     * by the worker. 0 = next to run. Absent for in-flight or terminal
+     * jobs (and for any backend that doesn't yet report position).
+     */
+    position?: number;
+    /**
+     * Estimated remaining seconds, derived server-side from the median
+     * historical duration for the user's follow-count bucket multiplied
+     * by `position + 1`. Absent when no historical data exists yet.
+     */
+    etaSeconds?: number;
+}
+/** Returned by `initiateNetworkMapGeneration` when a new job was started or one was already running. */
+interface NetworkMapPendingJob {
+    jobId: string;
+    status: 'pending' | 'cached';
+}
+/** Discriminate the union returned by `initiateNetworkMapGeneration`. */
+declare function isNetworkMapResponse(value: NetworkMapPendingJob | NetworkMapResponse): value is NetworkMapResponse;
+/**
+ * Kick off a personal network-map computation. The backend returns the
+ * cached map immediately when fresh, otherwise it returns a job id that
+ * the caller polls via `checkNetworkMapJobStatus`.
+ */
+declare function initiateNetworkMapGeneration(config: SifaApiConfig, options?: ApiFetchOptions): Promise<NetworkMapPendingJob | NetworkMapResponse>;
+/**
+ * Poll the status of an in-flight generation job. Throws on 404 (unknown
+ * or expired job) — callers may want to treat that as terminal failure.
+ */
+declare function checkNetworkMapJobStatus(config: SifaApiConfig, jobId: string, options?: ApiFetchOptions): Promise<NetworkMapGenerationJob>;
+/**
+ * Fetch the most recent cached network map for the authenticated user.
+ * Returns `null` when no map has ever been generated (404).
+ */
+declare function fetchNetworkMap(config: SifaApiConfig, options?: ApiFetchOptions): Promise<NetworkMapResponse | null>;
+
+export { resolveEntityDomain as A, revealMarqueDomain as B, selectEntity as C, setPositionPrimary as D, unhideKeytraceClaim as E, type FetchNetworkStreamCountOptions as F, unlinkSkillFromPosition as G, unrevealMarqueDomain as H, unsetPositionPrimary as I, updateEducation as J, updatePosition as K, updateRecord as L, updateSkill as M, type NetworkMapEdge as N, type NetworkMapGenerationJob as a, type NetworkMapGraphData as b, type NetworkMapNode as c, type NetworkMapPendingJob as d, type NetworkMapResponse as e, checkNetworkMapJobStatus as f, createEducation as g, createPosition as h, createRecord as i, createSkill as j, deleteEducation as k, deletePosition as l, deleteRecord as m, deleteSkill as n, fetchAtFundLink as o, fetchEndorsementCount as p, fetchEntitySearch as q, fetchNetworkMap as r, fetchNetworkStreamCount as s, fetchProfile as t, hideKeytraceClaim as u, importSearchEntities as v, initiateNetworkMapGeneration as w, isNetworkMapResponse as x, linkSkillToPosition as y, mintEntityDomain as z };