@juspay/neurolink/dist/proxy/shareGrants.d.ts

The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002

/**
 * Peer-sharing grant store.
 *
 * A grant is one lender-issued, revocable authorization for one borrower. This
 * module owns the persisted grant file and the token contract; it deliberately
 * knows nothing about admission policy (see `sharePolicy.ts`) or transport.
 *
 * **Token contract.** A share token looks like `nls_<grantId>_<secret>`. The
 * grant id is carried in the token so a lookup is a map hit rather than a scan
 * over every grant, and only then is the secret compared — in constant time —
 * against `sha256(salt + secret)`. The raw token exists exactly once, in the
 * return value of `createShareGrant`; nothing persists it.
 *
 * **Cross-process freshness.** The CLI mutates this file in one process while
 * the proxy reads it in another, so `share pause` has to land in a running
 * proxy without a restart. Reads therefore re-stat the file and reload when its
 * mtime moves, bounded by a short TTL so the hot path pays one `stat` per
 * second at most.
 *
 * @module proxy/shareGrants
 */
import type { ProxyShareGrant, ProxyShareGrantInput, ProxyShareGrantPatch, ProxyShareGrantState, ProxyShareIssuedGrant } from "../types/index.js";
/** Token prefix. Distinguishes a share token from a client's own credential. */
export declare const SHARE_TOKEN_PREFIX = "nls";
/** Point the store at an explicit file. Used by dev mode and by tests. */
export declare function initShareGrants(grantsFilePath: string): void;
/**
 * This node's stable public address.
 *
 * Recorded once — by `share url`, or by whatever already fronts this proxy — so
 * a link can be minted without retyping the domain. Nothing here assumes the
 * address came from `proxy expose`; a reverse proxy, a permanent named tunnel
 * or a plain DNS record are all the same thing to a borrower.
 */
export declare function getNodePublicUrl(): Promise<string | undefined>;
export declare function setNodePublicUrl(url: string | undefined): Promise<void>;
/**
 * Split a share token into its grant id and secret.
 * Returns null for anything that is not one of our tokens — including a client's
 * own Anthropic credential, which must never be mistaken for a share token.
 */
export declare function parseShareToken(token: string): {
    grantId: string;
    secret: string;
} | null;
export declare function looksLikeShareToken(token: string | undefined): boolean;
export declare function listShareGrants(): Promise<ProxyShareGrant[]>;
export declare function getShareGrant(id: string): Promise<ProxyShareGrant | undefined>;
/** Look a grant up by peer label (case-insensitive), the CLI's addressing form. */
export declare function findShareGrantByPeer(peerLabel: string): Promise<ProxyShareGrant | undefined>;
export declare function createShareGrant(input: ProxyShareGrantInput): Promise<ProxyShareIssuedGrant>;
/**
 * Replace a grant's token, keeping every control intact.
 * Used by `share revoke --rotate` and by any suspected token leak.
 */
export declare function rotateShareGrantToken(id: string): Promise<ProxyShareIssuedGrant | undefined>;
export declare function setShareGrantState(id: string, state: ProxyShareGrantState): Promise<ProxyShareGrant | undefined>;
export declare function updateShareGrant(id: string, patch: ProxyShareGrantPatch): Promise<ProxyShareGrant | undefined>;
/**
 * Attach complete-mode lease material to a grant.
 *
 * Separate from `updateShareGrant` because these are not policy the operator
 * edits — the secret is generated once and the borrower's copy is keyed to it,
 * so overwriting it silently would invalidate every lease already in the field.
 */
export declare function attachLeaseMaterial(id: string, leaseSecret: string, leasePolicy: {
    ttlMs: number;
    heartbeatEveryMs: number;
    offlineGraceMs: number;
}, provisionedAccount?: string): Promise<ProxyShareGrant | undefined>;
/**
 * Subtract settled spend from a metered grant's balance.
 *
 * Read-modify-write **inside** the store's mutex, because settlement is
 * concurrent by nature: two streams finishing together would otherwise both read
 * the same balance, and the second write would erase the first one's deduction.
 * Returns the new balance, or `undefined` for a grant that is not metered.
 */
export declare function debitShareGrantCoins(id: string, coins: number): Promise<number | undefined>;
/**
 * Add coins to a metered grant's balance.
 *
 * The mirror of `debitShareGrantCoins`, and under the same lock for the same
 * reason. Used by reciprocal netting, by `share topup`'s successor paths, and by
 * redeeming a coin note — all of which can land while requests are settling.
 */
export declare function creditShareGrantCoins(id: string, coins: number): Promise<number | undefined>;
/**
 * This node's secret for signing coin notes.
 *
 * Node-level rather than per-grant: a note may be redeemed by a grant that did
 * not exist when it was issued, which is the entire point of a transferable
 * one. Minted on first use so a node that never issues a note never has one.
 */
export declare function getOrCreateNoteSecret(): Promise<string>;
/** The note secret, without minting one. */
export declare function getNoteSecret(): Promise<string | undefined>;
export declare function deleteShareGrant(id: string): Promise<boolean>;
/**
 * Resolve a presented token to its grant.
 *
 * Returns the grant whatever its state — admission is `sharePolicy`'s decision,
 * and a paused grant must still be identifiable so the refusal can say *why*
 * rather than "unknown token".
 */
export declare function resolveShareToken(token: string): Promise<ProxyShareGrant | undefined>;
/**
 * Record that a grant served traffic.
 *
 * `lastUsedAt` is cosmetic, so it is held in memory and flushed at most once a
 * minute. Persisting it per request would put a file write on the hot path and —
 * worse — move the file's mtime constantly, forcing every reader to reload the
 * snapshot it just loaded.
 */
export declare function touchShareGrantUsage(id: string): void;