@oxy.so/core 1.18.1 → 3.0.0

package/dist/types/api/follows.d.ts

@@ -0,0 +1,236 @@
+/**
+ * `oxy.follows` — the follow graph.
+ *
+ * Two halves over one graph:
+ * - **People** (`follow`, `unfollow`, `status`, `followers`, …) — the user
+ *   follow routes (`/users/:id/follow…`). The SDK caches these reads and busts
+ *   them on every write.
+ * - **Targets** (`followTarget`, `targetStatus`, `list`, …) — the user-owned
+ *   graph (`/v2/follows`): one relationship per user and target (a topic, a
+ *   store, an artist, a channel), shared by every application, with
+ *   per-application context on top. Never cached here: a follow status served
+ *   stale across a write is the "follow reverts after navigating back" bug, so
+ *   the app's own store is the single cache authority.
+ */
+import type { FollowListPage, FollowMutation, FollowOptions, FollowStatus, UnfollowMutation } from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+import type { User } from '../models/interfaces';
+import { type FollowGraphParams } from '../utils/apiUtils';
+/** Response of `POST|DELETE /users/:id/follow`. */
+export interface FollowMutationResult {
+    /** Human-readable status message. */
+    message: string;
+    /** Which side of the toggle was applied, when reported. */
+    action?: 'follow' | 'unfollow';
+    /** Post-write counts, when reported. */
+    counts?: {
+        /** The target user's follower count after the write. */
+        followers: number;
+        /** The viewer's following count after the write. */
+        following: number;
+    };
+}
+/** Per-user outcome returned by `POST /users/follow/bulk`. */
+export interface BulkFollowEntry {
+    userId: string;
+    /** Whether the follow was applied (or already in place) without error. */
+    success: boolean;
+    /** Whether the caller already followed this user. */
+    alreadyFollowing: boolean;
+}
+/** Response of `POST /users/follow/bulk`. */
+export interface BulkFollowResult {
+    /** Per-user outcomes, in request order. */
+    results: BulkFollowEntry[];
+    /** Number of users newly followed. */
+    followedCount: number;
+}
+/** Per-user outcome returned by `POST /users/unfollow/bulk`. */
+export interface BulkUnfollowEntry {
+    userId: string;
+    /** Whether the unfollow was applied (or already absent) without error. */
+    success: boolean;
+    /** Whether the caller followed this user before. */
+    wasFollowing: boolean;
+}
+/** Response of `POST /users/unfollow/bulk`. */
+export interface BulkUnfollowResult {
+    /** Per-user outcomes, in request order. */
+    results: BulkUnfollowEntry[];
+    /** Number of users newly unfollowed. */
+    unfollowedCount: number;
+}
+/**
+ * The signed-in viewer's OWN social graph, ids only (`GET /users/me/graph`):
+ * who they follow, the mutuals among them, and who they blocked or restricted —
+ * one round trip instead of four. Each list is server-bounded.
+ */
+export interface ViewerGraph {
+    followingIds: string[];
+    mutualIds: string[];
+    blockedIds: string[];
+    restrictedIds: string[];
+}
+/** A registered follow target (`POST /v2/follow-targets`). */
+export interface EnsureFollowTargetInput {
+    uri: string;
+    kind: string;
+    metadata?: Record<string, unknown>;
+    providerReference?: string;
+    localUserId?: string;
+}
+/** What following a kind of thing means (`POST /v2/follow-targets/kinds`). */
+export interface RegisterFollowKindInput {
+    kind: string;
+    label?: string;
+    capabilities?: {
+        /** Matches `FollowVerb` in `@oxy.so/services`, which renders it. */
+        verb?: 'follow' | 'subscribe' | 'join' | 'watch';
+        reverse?: 'public' | 'private' | 'aggregate' | 'unavailable';
+        federated?: boolean;
+    };
+}
+type UserPage<K extends string> = {
+    [P in K]: User[];
+} & {
+    total: number;
+    hasMore: boolean;
+};
+export declare class FollowsApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /** Follow a user. */
+    follow(userId: string): Promise<FollowMutationResult>;
+    /** Follow many users in one request (the server caps it at 200). */
+    followMany(userIds: string[]): Promise<BulkFollowResult>;
+    /** Unfollow a user. */
+    unfollow(userId: string): Promise<FollowMutationResult>;
+    /** Unfollow many users in one request (the server caps it at 200). */
+    unfollowMany(userIds: string[]): Promise<BulkUnfollowResult>;
+    /** Whether the signed-in user follows `userId`. Cached 1 minute, busted by every write. */
+    status(userId: string): Promise<{
+        isFollowing: boolean;
+    }>;
+    /**
+     * Follow status for MANY users, one round-trip per chunk of 200 — for list
+     * UIs that would otherwise fire one `status` per button. Every requested id
+     * is in the result (`false` when not followed). Not cached: the UI store
+     * owns follow-status freshness.
+     */
+    statuses(userIds: string[]): Promise<Record<string, boolean>>;
+    /**
+     * A user's followers. `sort` is `recent` (default) or `oldest`; each
+     * `limit`/`offset`/`sort` combination is its own cache entry (2 minutes).
+     */
+    followers(userId: string, params?: FollowGraphParams): Promise<UserPage<'followers'>>;
+    /** Who a user follows. `sort` as in `followers`. */
+    following(userId: string, params?: FollowGraphParams): Promise<UserPage<'following'>>;
+    /**
+     * "Followers you know": users the signed-in viewer follows who also follow
+     * `userId`.
+     */
+    mutuals(userId: string, params?: FollowGraphParams): Promise<UserPage<'mutuals'>>;
+    /**
+     * The signed-in viewer's OWN mutuals, as ids — to seed a "Mutuals" feed.
+     * Signed out: `[]`. Cached 2 minutes.
+     */
+    mutualIds(params?: {
+        limit?: number;
+    }): Promise<string[]>;
+    /**
+     * The signed-in viewer's follows-of-follows (two hops, minus their own
+     * follows and themselves), as ids ordered by frequency then recency — to seed
+     * a friends-of-friends feed. Signed out: `[]`. Cached 2 minutes.
+     */
+    followsOfFollowsIds(params?: {
+        limit?: number;
+    }): Promise<string[]>;
+    /**
+     * The signed-in viewer's graph in one request (see {@link ViewerGraph}).
+     * Cached 2 minutes; follow, block and restrict writes bust it.
+     */
+    viewerGraph(): Promise<ViewerGraph>;
+    /**
+     * Follow a registered target (by id, not URI — see `ensureTarget`).
+     * Idempotent: an existing follow returns `created: false`. The follower and
+     * the acting application are both derived server-side; `expiresIn` (seconds)
+     * lets a follow lapse on its own.
+     */
+    followTarget(targetId: string, options?: FollowOptions): Promise<FollowMutation>;
+    /**
+     * Unfollow everywhere. ("Unfollow here" is `setApplicationMode(…,
+     * 'disabled')`.) Idempotent: `removed: false` when already gone.
+     */
+    unfollowTarget(relationshipId: string): Promise<UnfollowMutation>;
+    /**
+     * The three-part status — globally, in this application, in effect. Render
+     * `effectiveState`; keep the other two for the explanation.
+     */
+    targetStatus(targetId: string): Promise<FollowStatus>;
+    /**
+     * Turn a relationship off, or back on, in ONE application — the calling one
+     * unless `applicationId` names another (which needs `follows:manage`).
+     */
+    setApplicationMode(relationshipId: string, mode: 'enabled' | 'disabled', applicationId?: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Drop the override so the application follows the global relationship
+     * again (a later global change then takes effect here; an explicit
+     * `enabled` would not).
+     */
+    restoreInheritance(relationshipId: string, applicationId?: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Resolve a target by canonical URI, registering it the first time. Idempotent
+     * on the URI, so two applications describing the same thing reach ONE row.
+     * `metadata` is a display snapshot refreshed only by the providing app.
+     */
+    ensureTarget(input: EnsureFollowTargetInput): Promise<{
+        id: string;
+        uri: string;
+        kind: string;
+        created: boolean;
+    }>;
+    /** Claim a namespace for the calling application (first come; idempotent for the holder). */
+    claimNamespace(namespace: string): Promise<{
+        namespace: string;
+        created: boolean;
+    }>;
+    /**
+     * Release a namespace the calling application holds, while nothing is
+     * registered in it. Idempotent (`released: false` when already unowned).
+     */
+    releaseNamespace(namespace: string): Promise<{
+        namespace: string;
+        released: boolean;
+    }>;
+    /**
+     * Declare what following a kind of thing MEANS — the verb, whether reverse
+     * lookups are public, whether it federates. Once, by the owning application.
+     */
+    registerKind(input: RegisterFollowKindInput): Promise<{
+        kind: string;
+        created: boolean;
+    }>;
+    /**
+     * Everything the signed-in user follows, newest first. Paginate with
+     * `nextCursor`, never an offset: the list changes while it is read.
+     */
+    list(params?: {
+        kind?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<FollowListPage>;
+    private userPage;
+    /**
+     * Every cached read a follow write makes stale, in ONE pass over the cache.
+     *
+     * Lists go by PREFIX: they are paginated and sorted, so one logical list is
+     * spread over many content-addressed keys, and an exact-key clear would bust
+     * only the page read last.
+     */
+    private invalidate;
+}
+export {};

package/dist/types/api/identity.d.ts

@@ -0,0 +1,275 @@
+import type { AuthMethodsResponse, BackupStatusResponse, DidDocument, DomainVerificationInstructions, ExportBundle, IdentityLinkCreateResponse, IdentityLinkState, IdentityRootStatus, OxySignedRecordType, SignedRecordEnvelope, VerifiedDomain } from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+import type { PendingIdentityResult } from '../crypto/recoveryPhrase';
+/** Result of a successful domain verification (`POST /identity/domains/:domain/verify`). */
+export interface VerifyDomainResult {
+    verified: boolean;
+    domain: VerifiedDomain;
+}
+/** Result of removing a verified domain (`DELETE /identity/domains/:domain`). */
+export interface RemoveDomainResult {
+    success: boolean;
+}
+/** How the caller proves control of the CURRENT key during a key rotation. */
+export type RotateKeyProof = 'device' | 'phrase';
+/** Options for {@link IdentityApi.rotateKey}. */
+export interface RotateKeyOptions {
+    /**
+     * How to prove control of the CURRENT key:
+     *  - `'device'`: sign with the on-device SecureStore key (native-only).
+     *  - `'phrase'`: re-derive the current key from the entered recovery `phrase`
+     *    and sign with it. This works even when the device holds NO SecureStore
+     *    copy of the key — it is how the LAST remaining credential is replaced.
+     */
+    proof: RotateKeyProof;
+    /** The CURRENT identity's recovery phrase. Required when `proof: 'phrase'`. */
+    phrase?: string;
+    /**
+     * When true, all OTHER active sessions are revoked after a successful
+     * rotation (the rotating device stays signed in). Use it when the old key is
+     * presumed compromised.
+     */
+    signOutEverywhere?: boolean;
+    /**
+     * A pre-derived NEW identity to rotate to (from
+     * `RecoveryPhraseService.derivePendingIdentity`). Pass it when the UI derived +
+     * SHOWED the new phrase to the user BEFORE committing, so the SAME identity is
+     * the one rotated in. When omitted, a fresh identity is derived internally and
+     * its phrase is returned in the result.
+     */
+    pendingIdentity?: PendingIdentityResult;
+}
+/** Result of a successful key rotation. */
+export interface RotateKeyResult {
+    /** The account's new (rotated) public key. */
+    newPublicKey: string;
+    /**
+     * The NEW identity's recovery phrase. It MUST be surfaced to the user so they
+     * can back up the rotated key — if lost, the new identity is unrecoverable.
+     */
+    newPhrase: string;
+    /** The recovery phrase split into its individual words. */
+    words: string[];
+    /**
+     * Present (and `true`) only when the server rotated successfully but the new
+     * key could NOT be persisted on-device. The account key IS the new one
+     * server-side, so the user must re-import it from `newPhrase`; the caller
+     * should surface a recovery prompt. Omitted on full success.
+     */
+    localPersistFailed?: true;
+}
+/**
+ * Derive a user's Oxy DID from their stable account id.
+ * `did:web:oxy.so:u:<userId>`.
+ */
+export declare function buildUserDid(userId: string): string;
+/**
+ * Sign a self-issued v2 signed-record envelope on the CURRENT user's own
+ * per-subject hash chain. Fetches the chain head fresh (uncached, so `seq`/`prev`
+ * are never stale → no `bad_seq`/`chain_fork`) and signs with the on-device key.
+ *
+ * Shared by `oxy.civic` and `oxy.nodes`; not part of the public surface.
+ * NATIVE-ONLY. Throws before any network call when no user is signed in.
+ */
+export declare function signOwnChainRecord(ctx: OxyContext, type: OxySignedRecordType, record: Record<string, unknown>, key: {
+    collection: string;
+    rkey: string;
+}): Promise<SignedRecordEnvelope>;
+export declare class IdentityApi {
+    private readonly ctx;
+    /** Identity links: Commons' root joined to an account (ADR 0029 D3). */
+    readonly links: IdentityLinksApi;
+    /** Verified-domain badges. */
+    readonly domains: IdentityDomainsApi;
+    /** The encrypted off-device key backup. */
+    readonly backup: IdentityBackupApi;
+    constructor(ctx: OxyContext);
+    /**
+     * The signed-in user's DID (`did:web:oxy.so:u:<userId>`), derived locally from
+     * the access token. Throws when signed out.
+     */
+    get did(): string;
+    /**
+     * Resolve the W3C DID document for any user. The API derives it on demand
+     * from the account's `authMethods` + `publicKey` — there is no stored
+     * document. Public (no auth required); short-TTL cached.
+     */
+    resolveDid(userId: string): Promise<DidDocument>;
+    /**
+     * The signed-in user's linked authentication methods plus their DID. Each
+     * `identity` method carries a `verificationMethodId` linking it to its DID
+     * verification-method fragment.
+     */
+    authMethods(): Promise<AuthMethodsResponse>;
+    /**
+     * How the signed-in account is kept (ADR 0029 D3): whether Commons' root is
+     * linked (self-custody), or the email of an account without a key.
+     */
+    rootStatus(): Promise<IdentityRootStatus>;
+    /**
+     * Rotate the account's identity key: derive a brand-new keypair, prove
+     * control of the CURRENT key, and have the server ATOMICALLY replace the old
+     * key with the new one.
+     *
+     * The rotation is an atomic REPLACE on the server (never remove-then-add), so
+     * it never passes through a zero-auth-method state. Because control of the
+     * current key is PROVEN (from SecureStore in `'device'` mode, or a
+     * recovery-phrase re-derivation in `'phrase'` mode), even the LAST remaining
+     * credential can be replaced.
+     *
+     * Ordering (safety-critical): the new key is persisted on-device ONLY AFTER
+     * the server confirms the swap. Persisting earlier would clobber the local
+     * key while the server still trusts the old one, locking the device out.
+     *
+     * Ambiguous-network-failure guard: if the `complete` response is lost
+     * (request sent, no reply), the swap may already have applied server-side.
+     * Before surfacing the error we reconcile against the derived DID document —
+     * if it already advertises the new key, the rotation is treated as done.
+     *
+     * The UI is responsible for showing `newPhrase` to the user. For a
+     * "show-phrase-first" flow, derive the identity up front via
+     * `RecoveryPhraseService.derivePendingIdentity`, display it, then pass it back
+     * as `options.pendingIdentity` so the SAME identity is committed.
+     *
+     * @throws when no user is authenticated, when `proof: 'phrase'` is given
+     *   without a `phrase`, when `proof: 'device'` runs with no on-device key,
+     *   or when the rotation does not complete.
+     */
+    rotateKey(options: RotateKeyOptions): Promise<RotateKeyResult>;
+    /**
+     * The signed-in user's signed, open-format data-export bundle
+     * (`GET /users/me/export`) — the "credible exit" snapshot. Always carries an
+     * Oxy provenance `attestation`; carries an optional client `proof` when the
+     * account holds its own key.
+     */
+    export(): Promise<ExportBundle>;
+    /**
+     * Reconciliation probe for the rotation ambiguous-failure guard: whether the
+     * account's derived DID document (uncached) already advertises `newPublicKey`.
+     * A failed probe returns `false`, so the caller surfaces the original error.
+     *
+     * Uses the DID document rather than `GET /auth/methods` because the latter
+     * intentionally does NOT expose raw public keys, whereas the DID's
+     * `verificationMethod[].publicKeyHex` reflects a completed rotation at once.
+     */
+    private rotationAlreadyApplied;
+    /**
+     * Bust the cached reads an identity mutation invalidates: the current user
+     * (`/users/me*`), the auth-methods list, the verified-domains list, and the
+     * user's derived DID document (which embeds auth methods + verified domains).
+     */
+    private invalidate;
+}
+/** `oxy.identity.links` — joining Commons' root to an account (ADR 0029 D3). */
+export declare class IdentityLinksApi {
+    private readonly ctx;
+    private readonly invalidate;
+    constructor(ctx: OxyContext, invalidate: () => void);
+    /**
+     * Open a request to link Commons to the signed-in account.
+     * The "Link Commons" panel shows its `qrPayload`; Commons scans it and signs with `sign`.
+     */
+    create(): Promise<IdentityLinkCreateResponse>;
+    /** Where a link request stands. Both devices poll it; it needs no session. */
+    get(linkId: string): Promise<IdentityLinkState>;
+    /**
+     * Commons' half: sign the scanned request's `link_identity` proof with THIS
+     * device's identity key and post it. NATIVE-ONLY. Resolves to the key and the
+     * 6-digit code the other screen will show for it, for the person to compare.
+     */
+    sign(linkId: string, challenge: string): Promise<{
+        publicKey: string;
+        code: string;
+        username: string | null;
+    }>;
+    /**
+     * Complete a link with a code just sent to the account's email
+     * (`oxy.auth.requestReauthCode`) — plus its authenticator code when it has
+     * one. The account gains Commons' root and loses its email; every other
+     * session of the account is signed out.
+     */
+    complete(linkId: string, reauth: {
+        emailCode: {
+            verificationId: string;
+            code: string;
+        };
+        totpCode?: string;
+    }): Promise<{
+        success: true;
+    }>;
+    /** Withdraw a link request that has not completed. */
+    cancel(linkId: string): Promise<void>;
+}
+/** `oxy.identity.domains` — verified-domain badges (prove ownership of `nate.com`). */
+export declare class IdentityDomainsApi {
+    private readonly ctx;
+    private readonly invalidate;
+    constructor(ctx: OxyContext, invalidate: () => void);
+    /**
+     * Start verifying ownership of a domain. Returns the instructions: publish
+     * EITHER the DNS-TXT record OR the `/.well-known/oxy-domain` file, then call
+     * `verify`.
+     */
+    requestVerification(domain: string): Promise<DomainVerificationInstructions>;
+    /**
+     * Complete domain verification: the server checks the DNS-TXT record or
+     * well-known file and, on success, attaches the domain to the account
+     * (surfaced in the DID's `alsoKnownAs` and the user's `verifiedDomains`).
+     */
+    verify(domain: string): Promise<VerifyDomainResult>;
+    /** The signed-in user's verified domains. */
+    list(): Promise<VerifiedDomain[]>;
+    /** Remove a verified domain from the signed-in account. */
+    remove(domain: string): Promise<RemoveDomainResult>;
+}
+/**
+ * `oxy.identity.backup` — an ENCRYPTED copy of the self-custody key, stored
+ * off-device so a lost device can be recovered from the recovery phrase alone,
+ * while the platform never sees the phrase, the derived key, or the plaintext.
+ *
+ * Key schedule (from the recovery phrase; `RecoveryPhraseService.deriveBackupMaterial`):
+ *   seed      = mnemonicToSeed(phrase)
+ *   backupKey = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-encryption-key')
+ *   lookupId  = HKDF(seed, 'oxy-identity-backup-v1', 'oxy-backup-lookup-id')
+ *
+ * Both need the FULL seed, so leaking only the raw private key can neither
+ * locate nor decrypt the backup. Persisting a restored key is NATIVE-ONLY.
+ */
+export declare class IdentityBackupApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /**
+     * Encrypt the identity derived from `phrase` and upload the ciphertext + raw
+     * `lookupId` (`POST /identity/backup`). The server stores only
+     * `sha256(lookupId)` + the ciphertext. A re-upload REPLACES the prior backup.
+     * Works cross-platform: the identity is derived from the phrase, not read
+     * from SecureStore.
+     */
+    create(phrase: string): Promise<BackupStatusResponse>;
+    /**
+     * Whether the signed-in user has a stored backup, plus its non-sensitive hint
+     * and timestamp. Returns no ciphertext and no locator.
+     */
+    status(): Promise<BackupStatusResponse>;
+    /** Delete the signed-in user's stored backup. Idempotent. */
+    delete(): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Restore an identity from its encrypted backup using ONLY the recovery
+     * phrase: re-derive `{backupKey, lookupId}`, fetch the envelope by `lookupId`
+     * (PUBLIC — the 256-bit locator is the protection), decrypt + authenticate
+     * locally, then persist the key.
+     *
+     * NATIVE-ONLY persistence. Refuses to clobber a DIFFERENT existing on-device
+     * identity unless `overwrite: true` — the `IdentityAlreadyExistsError`
+     * propagates so the UI can confirm before overwriting.
+     *
+     * @returns The restored identity's public key.
+     * @throws if the phrase is invalid, no backup exists (404), the ciphertext
+     *   fails authentication (tamper), or an existing identity blocks the import.
+     */
+    restore(phrase: string, options?: {
+        overwrite?: boolean;
+    }): Promise<string>;
+}

package/dist/types/api/linkedAccounts.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `oxy.linkedAccounts` — external accounts (any Mastodon-API server, Bluesky)
+ * the current user has PROVEN they own by completing an OAuth authorization
+ * there. Oxy uses that authorization only to learn which account granted it and
+ * then discards the token — nothing here ever carries a third-party token.
+ *
+ * The flow is a top-level browser navigation: `start` returns the other
+ * network's `authorizeUrl`; open it (a new tab, or `expo-web-browser`'s auth
+ * session on native); the network sends the browser to Oxy's callback, and Oxy
+ * sends it to `returnTo` with `?link_code=<code>` or `?link_error=<code>`. Pass
+ * the code to `complete` with the same user signed in: that call, not the
+ * callback, creates the link, so an authorization someone else started can
+ * never link to them. `returnTo` must be a redirect URI registered on the
+ * first-party application `clientId` names.
+ *
+ * Wire types live in `@oxy.so/contracts` (`linkedAccounts.ts`).
+ */
+import type { LinkedAccount, LinkedAccountNetwork, StartLinkedAccountRequest, StartLinkedAccountResponse } from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+export declare class LinkedAccountsApi {
+    protected readonly ctx: OxyContext;
+    constructor(ctx: OxyContext);
+    /**
+     * Begin linking an external account for the current user.
+     *
+     * @param network - `'activitypub'` (any Mastodon-API server) or `'atproto'` (Bluesky).
+     * @param options - `instance` for ActivityPub (`mastodon.social`, or
+     *   `@user@mastodon.social`), `handle` for atproto; `clientId` + `returnTo`
+     *   to be sent back to your app afterwards.
+     * @returns The URL to open, and when the attempt expires (ten minutes).
+     */
+    start(network: LinkedAccountNetwork, options: StartLinkedAccountRequest): Promise<StartLinkedAccountResponse>;
+    /**
+     * Finish a link with the `link_code` the callback appended to `returnTo`.
+     * Must be the user who started the flow: for anyone else the API answers 403
+     * and burns the code. 409 when the account is already someone else's link.
+     * Repeating it within the code's five minutes returns the same link.
+     */
+    complete(code: string): Promise<LinkedAccount>;
+    /** The current user's live linked accounts, oldest first. */
+    list(): Promise<LinkedAccount[]>;
+    /**
+     * Unlink one of the current user's accounts. An ActivityPub link stops being
+     * published as an `alsoKnownAs` alias, and the external account can then be
+     * linked to another Oxy account.
+     */
+    revoke(linkedAccountId: string): Promise<void>;
+}

package/dist/types/api/nodes.d.ts

@@ -0,0 +1,102 @@
+/**
+ * `oxy.nodes` — the signed-in user's personal data NODE: the decentralised store
+ * that holds an authentic copy of their signed-record chain.
+ *
+ *  - `register` registers (or re-registers) a SELF-HOSTED node. It is a signed
+ *    `type:'node'` v2 record (`collection: 'app.oxy.node'`, `rkey: 'self'`,
+ *    last-writer-wins) published through `POST /identity/records`; the server
+ *    verifies it and materializes the node status as a side effect, so the
+ *    registration's authority is the user's own signature. NATIVE-ONLY.
+ *  - `mine` reads the cached node status plus the liveness badge Oxy maintains.
+ *  - `removeMine` revokes the registration.
+ *  - `provisionManagedVault` asks Oxy to operate a MANAGED vault (`managed:true,
+ *    controller:'oxy'`) — the "Create your vault" convenience.
+ *  - `notifyIngest` sends an unauthenticated HINT that a node has new records;
+ *    the server fully re-verifies before ingesting, so it can never inject data.
+ *
+ * The wire shapes are API-internal (not yet a published contract), so
+ * {@link UserNodeStatus} mirrors the server's `serializeNode` projection.
+ */
+import type { OxyContext } from '../client/context';
+/** How Oxy and the node move records: the node pulls (default), or Oxy pushes. */
+export type UserNodeMode = 'pull' | 'push';
+/** Who operates the node: the user (`self`) or Oxy on their behalf (`oxy`). */
+export type UserNodeController = 'self' | 'oxy';
+/**
+ * Liveness badge, maintained ONLY by Oxy's background probes: `active` (the
+ * last probe reached the manifest), `unreachable` (it failed; the cached row is
+ * still served), `revoked` (the user removed the registration).
+ */
+export type UserNodeLivenessStatus = 'active' | 'unreachable' | 'revoked';
+/** The caller's registered node, as projected by the server. Dates are ISO strings. */
+export interface UserNodeStatus {
+    /** Optional DID the node advertises for itself (informational). */
+    nodeDid?: string;
+    /** The node's public HTTPS base URL (where its liveness manifest lives). */
+    endpoint: string;
+    /** The node's secp256k1 public key (hex) — records it signs verify against this. */
+    nodePublicKey: string;
+    /** Transport direction. `pull` by default. */
+    mode: UserNodeMode;
+    /** Whether Oxy operates this node on the user's behalf (managed vault). */
+    managed: boolean;
+    /** Operator of the node. */
+    controller: UserNodeController;
+    /** Liveness badge — maintained only by background probes. */
+    status: UserNodeLivenessStatus;
+    /** Last time a probe reached the node successfully. */
+    lastSeenAt?: string;
+    /** Last time a probe ran, success or failure. */
+    lastProbeAt?: string;
+    /** Why the last probe OR ingest failed (cleared on success). */
+    lastError?: string;
+    /** Last synced chain `seq` (advanced only by the ingest worker). */
+    cursor?: number;
+    /** Last time the ingest worker pulled this node. */
+    lastSyncedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Input for {@link NodesApi.register}. */
+export interface RegisterNodeInput {
+    /** The node's public HTTPS base URL. */
+    endpoint: string;
+    /** The node's secp256k1 public key (hex). */
+    nodePublicKey: string;
+    /** Transport direction; `'pull'` when omitted. */
+    mode?: UserNodeMode;
+}
+/** Result of {@link NodesApi.removeMine}. */
+export interface RemoveNodeResult {
+    /** `true` when an active registration was flipped to `revoked`. */
+    revoked: boolean;
+}
+export declare class NodesApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /**
+     * Register (or re-register) the signed-in user's SELF-HOSTED node: sign the
+     * `{ endpoint, nodePublicKey, mode }` record on the caller's own chain and
+     * publish it. NATIVE-ONLY; throws before any network call when signed out.
+     * Returns the freshly materialized status.
+     *
+     * Throws if the record stored but the server skipped materialization (e.g. a
+     * malformed endpoint it rejected) rather than returning a silent `null`.
+     */
+    register(input: RegisterNodeInput): Promise<UserNodeStatus>;
+    /** The signed-in user's node status, or `null` when they have none. Short-TTL cached. */
+    mine(): Promise<UserNodeStatus | null>;
+    /** Revoke the signed-in user's node registration. */
+    removeMine(): Promise<RemoveNodeResult>;
+    /**
+     * Provision (or refresh) an Oxy-operated MANAGED vault for the signed-in
+     * user. Idempotent server-side; the owner comes from the session.
+     */
+    provisionManagedVault(): Promise<UserNodeStatus>;
+    /**
+     * Hint that `userId`'s node has new records. Unauthenticated by design and
+     * fire-and-forget on the server (a 202); resolves once accepted.
+     */
+    notifyIngest(userId: string): Promise<void>;
+    private sweep;
+}