@kubun/store-p2p 0.11.0 → 0.12.0

package/lib/api.d.ts

@@ -1,254 +1,28 @@
 import type { Adapter } from '@kubun/db-adapter';
 import type { Kysely } from 'kysely';
-import type { Circle, CircleMember, ControlLedgerEntry, Group, GroupMember, GroupMLSState, Hub, InsertCircle, InsertCircleMember, InsertControlLedgerEntry, InsertGroup, InsertGroupDelegation, InsertGroupHub, InsertGroupMember, InsertGroupMLSState, InsertHub, InsertSyncPeer, P2PStoreTables, PaginatedResult, PaginationParams, SyncPeer } from './tables.js';
-export type P2PStoreAPI = {
-    createGroup(group: InsertGroup): Promise<void>;
-    getGroup(id: string): Promise<Group | undefined>;
-    updateGroup(id: string, update: Partial<Pick<InsertGroup, 'name' | 'description' | 'hlc'>>): Promise<void>;
-    deleteGroup(id: string): Promise<void>;
-    listGroups(): Promise<Array<Group>>;
-    listGroupsOffsetPaged(params: PaginationParams): Promise<PaginatedResult<Group>>;
-    addGroupMember(member: InsertGroupMember): Promise<void>;
-    /**
-     * Add (or revive) several members in a single multi-row insert. Same
-     * re-add-clears-tombstone semantics as {@link addGroupMember}, applied to every
-     * row. A single statement keeps the whole batch atomic and avoids issuing one
-     * round-trip per member on a single-connection adapter. A no-op for an empty list.
-     */
-    addGroupMembers(members: Array<InsertGroupMember>): Promise<void>;
-    /**
-     * Soft-delete a member by tombstoning the row with `hlc`. Delegates to
-     * `markMemberRemoved`: earliest-wins LWW, ignore-if-absent. The row stays in
-     * the table (read queries exclude it) so the apply-time check can compare a
-     * mutation's HLC against the removal HLC.
-     */
-    removeGroupMember(groupID: string, memberDID: string, hlc: string): Promise<void>;
-    /**
-     * Tombstone an existing membership row at `hlc` using earliest-wins LWW: the
-     * removal sticks only when no removal is recorded yet, or when `hlc` precedes
-     * the stored removal HLC. A removal for a `(groupID, memberDID)` with no local
-     * row is a no-op — absence means there is no member to tombstone, and no row
-     * is created.
-     */
-    markMemberRemoved(groupID: string, memberDID: string, hlc: string): Promise<void>;
-    /**
-     * Read a membership row's removal state, including tombstoned rows. This is
-     * the only query that sees soft-deleted members. Returns `undefined` when no
-     * row exists; `{ removed_at_hlc: null }` for an active member; and
-     * `{ removed_at_hlc: <hlc> }` for a removed one.
-     */
-    getMemberRemoval(groupID: string, memberDID: string): Promise<{
-        removed_at_hlc: string | null;
-    } | undefined>;
-    getGroupMember(groupID: string, memberDID: string): Promise<GroupMember | undefined>;
-    isGroupMember(groupID: string, memberDID: string): Promise<boolean>;
-    /**
-     * Whether `did` was a member of `groupID` at the given HLC, ignoring role.
-     * Mirrors {@link isGroupAdmin}'s removal-boundary semantics without the
-     * `role = 'admin'` filter: with no `atHLC`, tombstoned rows are excluded
-     * (`removed_at_hlc IS NULL`); with `atHLC`, a member removed at HLC `R` still
-     * counts iff `atHLC < R`. Conjoined with ledger admin authority so an
-     * MLS-removed member loses admin regardless of the ledger.
-     */
-    isGroupMemberAtHLC(groupID: string, did: string, atHLC?: string): Promise<boolean>;
-    /**
-     * Whether `did` holds an active `admin` role in `groupID`. With no `atHLC`,
-     * tombstoned rows are ignored (`removed_at_hlc IS NULL`) — the apply-time
-     * admin check. With `atHLC`, an admin removed at HLC `R` still counts iff the
-     * supplied HLC strictly precedes `R` (`atHLC < R`): a write claiming a moment
-     * before the removal is admitted, one at or after it is denied. This mirrors
-     * the membership boundary in `checkMembership` (which denies at
-     * `removed_at_hlc <= mutationHLC`), so the two checks agree on the
-     * remove-boundary instant.
-     */
-    isGroupAdmin(groupID: string, did: string, atHLC?: string): Promise<boolean>;
-    /**
-     * Overlay the role column for an existing member. Update-only: a grant for a
-     * DID with no membership row is a no-op, since membership is MLS-native and a
-     * non-member can hold no role. Never touches `hlc` or `removed_at_hlc`, so it
-     * neither churns membership LWW nor resurrects a tombstone — it is purely the
-     * projection target for the admin-roster fold.
-     */
-    setGroupMemberRole(groupID: string, memberDID: string, role: string): Promise<void>;
-    isMemberOfAnyGroup(viewerDID: string, groupIDs: Array<string>): Promise<boolean>;
-    listGroupMembers(groupID: string): Promise<Array<GroupMember>>;
-    getGroupsForMember(memberDID: string): Promise<Array<Group>>;
-    /**
-     * Batch fetch groups for multiple members. Returns a Map keyed by
-     * `memberDID`; values are arrays of groups for that member. Members with
-     * no groups are absent from the map. Single SQL query joining
-     * `group_members` to `groups`. Empty input short-circuits with an empty
-     * Map (no SQL).
-     *
-     * Caller is responsible for deduplicating DIDs.
-     */
-    getGroupsForMembers(memberDIDs: Array<string>): Promise<Map<string, Array<Group>>>;
-    createCircle(circle: InsertCircle): Promise<void>;
-    /**
-     * Active-only by default (`removed_at_hlc IS NULL`). Pass
-     * `{ includeRemoved: true }` to also see tombstoned circles — used by the
-     * apply path so a `circle:create`/`circle:update` can HLC-compare against a
-     * tombstoned row and resurrect it, and by the catch-up responder.
-     */
-    getCircle(id: string, options?: {
-        includeRemoved?: boolean;
-    }): Promise<Circle | undefined>;
-    /**
-     * Batch fetch circles by ID. Returns a Map keyed by ID; missing IDs are
-     * absent from the map. Single SQL query with `WHERE id IN (...)`. Empty
-     * input short-circuits with an empty Map (no SQL).
-     *
-     * Caller is responsible for deduplicating IDs.
-     */
-    getCircles(ids: Array<string>): Promise<Map<string, Circle>>;
-    updateCircle(id: string, update: Partial<Pick<InsertCircle, 'name' | 'description' | 'catalog_ids' | 'hlc'>>): Promise<void>;
-    deleteCircle(id: string): Promise<void>;
-    /**
-     * Tombstone an existing circle row at `hlc` using earliest-wins LWW: the
-     * removal sticks only when no removal is recorded yet, or when `hlc` precedes
-     * the stored removal HLC. A removal for a `circleID` with no local row is a
-     * no-op — absence means there is no circle to tombstone, and no row is
-     * created.
-     */
-    markCircleRemoved(circleID: string, hlc: string): Promise<void>;
-    /**
-     * Active-only by default (`removed_at_hlc IS NULL`). Pass
-     * `{ includeRemoved: true }` to include tombstoned circles for the catch-up
-     * responder.
-     */
-    listCirclesByGroup(groupID: string, options?: {
-        includeRemoved?: boolean;
-    }): Promise<Array<Circle>>;
-    addCircleMember(member: InsertCircleMember): Promise<void>;
-    /**
-     * Soft-delete a circle member by tombstoning the row with `hlc`: earliest-wins
-     * LWW, ignore-if-absent. The row stays in the table so the removal HLC stays
-     * comparable.
-     */
-    removeCircleMember(circleID: string, memberDID: string, hlc: string): Promise<void>;
-    getCircleMember(circleID: string, memberDID: string): Promise<CircleMember | undefined>;
-    /**
-     * Active-only by default (`removed_at_hlc IS NULL`). Pass
-     * `{ includeRemoved: true }` to include tombstoned members for the catch-up
-     * responder.
-     */
-    listCircleMembers(circleID: string, options?: {
-        includeRemoved?: boolean;
-    }): Promise<Array<CircleMember>>;
-    getCirclesForMember(memberDID: string): Promise<Array<Circle>>;
-    isMemberOfAnyCircle(memberDID: string, circleIDs: Array<string>): Promise<boolean>;
-    /**
-     * Fold-authoritative circle projection write: unconditionally set the row for
-     * `id` to the supplied derived state. Distinct from the LWW writers —
-     * `createCircle` (insert-only), `updateCircle` (update-only, clears the
-     * tombstone) and `markCircleRemoved` (earliest-wins LWW). A reproject derives
-     * `hlc` from the winning active entry and `removedAtHLC` from the winning
-     * tombstone (or null when active), then overwrites every projected column so
-     * the row equals exactly what the ledger fold decides regardless of prior
-     * contents. A removed circle keeps a tombstone row (`removed_at_hlc` set), not
-     * a hard delete, so `includeRemoved` reads and the read-ACL joins keep working.
-     */
-    reconcileCircleProjection(params: {
-        id: string;
-        groupID: string;
-        name: string;
-        description: string;
-        catalogIDs: Array<string>;
-        hlc: string;
-        removedAtHLC: string | null;
-    }): Promise<void>;
-    /**
-     * Fold-authoritative circle-member projection write, the member-row analogue
-     * of {@link reconcileCircleProjection}: unconditionally upsert the
-     * `(circleID, memberDID)` row to the derived `(role, hlc, removedAtHLC)` state.
-     * A removed member keeps a tombstone row so the read-ACL joins still gate on
-     * the marker.
-     */
-    reconcileCircleMemberProjection(params: {
-        circleID: string;
-        memberDID: string;
-        role: string;
-        hlc: string;
-        removedAtHLC: string | null;
-    }): Promise<void>;
-    /**
-     * Record the group a delegation `jti` was granted in. Idempotent on `jti`
-     * (the primary key): a re-record for a `jti` already present is a no-op. The
-     * delegation token itself lives in the core delegation store; this edge only
-     * carries the group association the p2p layer needs.
-     */
-    addGroupDelegation(edge: InsertGroupDelegation): Promise<void>;
-    /**
-     * Resolve the group a delegation `jti` was granted in, or `null` when no edge
-     * exists. Used to target revoke broadcasts and to enrich revocation listings
-     * with their originating group.
-     */
-    getGroupIDByJTI(jti: string): Promise<string | null>;
-    /**
-     * Batch variant of {@link getGroupIDByJTI}: resolve the group each `jti` was
-     * granted in, returning a `Map` keyed by `jti`. A `jti` with no edge is absent
-     * from the map. Used to enrich revocation listings without an N+1 lookup.
-     */
-    getGroupIDsByJTIs(jtis: Array<string>): Promise<Map<string, string>>;
-    saveMLSState(state: InsertGroupMLSState): Promise<void>;
-    getMLSState(groupID: string, deviceID: string): Promise<GroupMLSState | undefined>;
-    deleteMLSState(groupID: string, deviceID: string): Promise<void>;
-    listMLSStates(groupID: string): Promise<Array<GroupMLSState>>;
-    deleteGroupMLSStates(groupID: string): Promise<void>;
-    addSyncPeer(peer: InsertSyncPeer): Promise<void>;
-    getSyncPeer(peerDID: string): Promise<SyncPeer | undefined>;
-    listSyncPeers(): Promise<Array<SyncPeer>>;
-    updateSyncPeer(peerDID: string, update: Partial<InsertSyncPeer>): Promise<void>;
-    removeSyncPeer(peerDID: string): Promise<void>;
-    recordBroadcast(entry: {
-        docID: string;
-        version: string;
-        mlsGroupID: string;
-    }): Promise<boolean>;
-    hasBroadcast(entry: {
-        docID: string;
-        version: string;
-        mlsGroupID: string;
-    }): Promise<boolean>;
-    /**
-     * Append a verified ledger entry. Idempotent on `entry_id` (the token
-     * digest): a re-delivered entry is a no-op. `issuer_did` is normalized on
-     * write. Returns `true` when a new row was inserted, `false` on a duplicate.
-     */
-    appendLedgerEntry(entry: InsertControlLedgerEntry): Promise<boolean>;
-    /** All ledger entries for a group, ordered by `(hlc, entry_id)`. */
-    getLedgerEntries(groupID: string): Promise<Array<ControlLedgerEntry>>;
-    /** Ledger entries for a group filtered by `type`, ordered by `(hlc, entry_id)`. */
-    getLedgerEntriesByType(groupID: string, type: string): Promise<Array<ControlLedgerEntry>>;
-    /**
-     * The HLC through which `projection` has been folded for `groupID`, or `null`
-     * when no projection has run yet. A caller treats an entry whose HLC is `>`
-     * this value as in-order (apply incrementally); `<=` or `null` means the
-     * cached projection is no longer a correct fold-through-this-entry and must be
-     * rebuilt from the whole ledger.
-     */
-    getProjectionWatermark(groupID: string, projection: string): Promise<string | null>;
-    /**
-     * Set the `(groupID, projection)` watermark to `hlc`. Overwrite-on-conflict:
-     * the row is unconditionally replaced. Callers must only advance the watermark
-     * — the incremental path passes a value strictly newer than the current one,
-     * and the reproject path passes the true max over the folded ledger.
-     */
-    setProjectionWatermark(groupID: string, projection: string, hlc: string): Promise<void>;
-    insertHub(hub: InsertHub): Promise<void>;
-    getHub(id: string): Promise<Hub | undefined>;
-    getHubByURL(url: string): Promise<Hub | undefined>;
-    updateHub(id: string, update: Partial<Pick<InsertHub, 'label' | 'url' | 'server_did'>>): Promise<void>;
-    deleteHub(id: string): Promise<void>;
-    listHubs(): Promise<Array<Hub>>;
-    insertGroupHub(binding: InsertGroupHub): Promise<boolean>;
-    deleteGroupHub(params: {
-        groupID: string;
-        hubID: string;
-    }): Promise<boolean>;
-    listGroupIDsByHubID(hubID: string): Promise<Array<string>>;
-    listHubsByGroupID(groupID: string): Promise<Array<Hub>>;
-    listGroupsByHubID(hubID: string): Promise<Array<Group>>;
-    deleteGroupHubsByHubID(hubID: string): Promise<void>;
-};
+import { type AppLaneOps } from './ops/app-lane.js';
+import { type CircleOps } from './ops/circles.js';
+import { type ControlOps } from './ops/control.js';
+import { type DelegationOps } from './ops/delegations.js';
+import { type DiscoveryOps } from './ops/discovery.js';
+import { type GroupOps } from './ops/groups.js';
+import { type HubOps } from './ops/hubs.js';
+import { type MLSOps } from './ops/mls.js';
+import { type SyncOps } from './ops/sync.js';
+import type { P2PStoreTables } from './tables.js';
+export type { AppLaneOps } from './ops/app-lane.js';
+export type { CircleOps } from './ops/circles.js';
+export type { CommitJournalEntryKind, ControlOps, ControlRequestKind, ControlRequestOutcome, } from './ops/control.js';
+export type { DelegationOps } from './ops/delegations.js';
+export type { DiscoveryOps, PutPendingJoinRequestParams, SetLocalPeerProfileParams, UpsertPeerAnnouncementParams, } from './ops/discovery.js';
+export type { GroupOps } from './ops/groups.js';
+export type { HubOps } from './ops/hubs.js';
+export type { MLSOps } from './ops/mls.js';
+export type { SyncOps } from './ops/sync.js';
+/**
+ * The store's whole surface, one slice per domain. Each slice module owns its
+ * tables and its own helpers; this intersection is the only coupling between
+ * them, so a caller still sees one flat API.
+ */
+export type P2PStoreAPI = GroupOps & CircleOps & DelegationOps & MLSOps & SyncOps & ControlOps & AppLaneOps & HubOps & DiscoveryOps;
 export declare function createP2PStore(db: Kysely<P2PStoreTables>, adapter: Adapter): P2PStoreAPI;