@drakkar.software/octospaces-sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,221 @@
+/** @drakkar.software/octospaces-sdk — public surface */
+
+// Configuration
+export { configureOctoSpaces, getSyncBase, getSyncNamespace, getSyncPrefix, getSharedSpacesNamespace } from './core/config.js';
+export type { OctoSpacesConfig } from './core/config.js';
+
+// KV adapter
+export { configureKv, kvGet, kvSet, kvRemove } from './core/adapters.js';
+export type { KvAdapter } from './core/adapters.js';
+
+// Domain types
+export type {
+  ID,
+  ObjectNode,
+  ObjectType,
+  ObjectsIndex,
+  ObjectContentKind,
+  RoomSubtype,
+  AutomationMeta,
+  Room,
+  RoomKind,
+  Space,
+  SpaceVisibility,
+  CapMap,
+  PubAccessMap,
+  DmMap,
+  MutePrefs,
+  ReadPrefs,
+  ArchivedDms,
+  BUILTIN_OBJECT_TYPES,
+} from './core/types.js';
+
+// Ids
+export { randomId, roomSlug } from './core/ids.js';
+
+// Paths / cap scopes
+export {
+  OBJECT_COLLECTIONS,
+  ownerScope,
+  spaceMemberScope,
+  accountScope,
+  linkedDeviceScope,
+  keyringName,
+  keyringPull,
+  keyringPush,
+  objIndexPull,
+  objIndexPush,
+  spacesPull,
+  spacesPush,
+  roomsRegistryPull,
+  roomsRegistryPush,
+  profilePull,
+  profilePush,
+  objLogPull,
+  objLogPush,
+  objDocPull,
+  objDocPush,
+  objectBlobPull,
+  objectBlobPush,
+  typesIndexPull,
+  typesIndexPush,
+  attachmentPull,
+  attachmentPush,
+  spaceIndexPull,
+  userIdFromEdPub,
+  bytesToHex,
+} from './sync/paths.js';
+
+// Client
+export {
+  makeClient,
+  capProviderFor,
+  openEncryptor,
+  buildEncryptor,
+  ownerEnsureKeyring,
+  readProfile,
+  readPseudo,
+  readProfiles,
+  writeProfile,
+  writePseudo,
+  ensureProfileKeys,
+  buildAuthHeaders,
+  ensurePseudo,
+} from './sync/client.js';
+export type { DeviceKeys, PublicProfile } from './sync/client.js';
+
+// Identity / session
+export {
+  buildSession,
+  buildLinkedSession,
+  deriveSession,
+  rootIdentityOf,
+  ownerTrustedAdders,
+  generateSeedWords,
+  isValidSeed,
+  fingerprintFromUserId,
+} from './sync/identity.js';
+export type { Session, LinkedIdentity } from './sync/identity.js';
+
+// Storage types
+export type {
+  DerivedIdentity,
+  PersistedSession,
+  Vault,
+  VaultLoad,
+  UnlockMethod,
+  PasskeyEnrollment,
+  SeedLock,
+} from './core/storage-types.js';
+
+// Sealed blobs
+export { sealToSelf, unsealFromSelf, sealToRecipient, unsealFromRecipient } from './sync/account-seal.js';
+export type { SealedBlob } from './sync/account-seal.js';
+
+// Space access (replaces SpaceEncryptor)
+export { SpaceAccessError, getSpaceAccess, buildSpaceAccess, clearSpaceAccessCache } from './sync/space-access.js';
+export type { SpaceAccessHandle } from './sync/space-access.js';
+
+// Space access store (replaces member-caps + pubspace-caps)
+export {
+  hydrateSpaceAccessStore,
+  getSpaceAccessEntry,
+  saveSpaceAccessEntry,
+  removeSpaceAccessEntry,
+  localSpaceAccessEntries,
+  memberCapsFromStore,
+  linkAccessFromStore,
+  clearSpaceAccessStore,
+} from './sync/space-access-store.js';
+export type { SpaceAccessEntry, SpaceAccessMap } from './sync/space-access-store.js';
+
+// Registry
+export {
+  DEFAULT_CATEGORY,
+  readSpaces,
+  updateSpacesDoc,
+  updateMutesDoc,
+  updateReadsDoc,
+  updateDmsDoc,
+  updateQuickReactionsDoc,
+  updateArchivedDmsDoc,
+  setDmMapping,
+  writeSpaces,
+  reorderSpaces,
+  readRooms,
+  writeRooms,
+  addSpaceMember,
+  removeSpaceMember,
+  addJoinedSpace,
+  addJoinedSpaceWithCap,
+  addJoinedSpaceWithLinkAccess,
+  createSpace,
+  normalizeCategories,
+  reconcileSpaceMeta,
+  onSpaceMeta,
+  broadcastSpaceMeta,
+  CategoryError,
+} from './spaces/registry.js';
+export type { SpaceMeta, SpaceMetaUpdate } from './spaces/registry.js';
+
+// Members
+export {
+  makeJoinRequest,
+  inviteToSpace,
+  acceptSpaceInvite,
+  addDeviceToSpaceKeyring,
+  encodeSpaceInviteLink,
+  decodeSpaceInviteLink,
+  createSpaceInviteLink,
+  joinSpaceByLink,
+  recoverSpaceAccess,
+} from './spaces/members.js';
+export type { JoinRequest, SpaceInviteLinkToken } from './spaces/members.js';
+
+// Object core
+export {
+  categoryId,
+  buildTree,
+  breadcrumbs,
+  ancestors,
+  subtreeIds,
+  nextOrder,
+  addObject,
+  patchObject,
+  reparentObject,
+  reorderObjects,
+  archiveObject,
+  seedIndexNodes,
+  objectsToRoomCategories,
+  excludeAutomatedRooms,
+  roomKindToSubtype,
+  subtypeToRoomKind,
+} from './objects/objects.js';
+export type { ObjectTreeNode, NewObjectInput, AdaptedCategory, SeedRoom } from './objects/objects.js';
+
+// Object index
+export {
+  readIndexRooms,
+  readSpaceIndexRooms,
+  readSpaceRooms,
+  pushIndexSeed,
+  seedSpaceObjectIndex,
+  updateObjectIndex,
+} from './spaces/object-index.js';
+
+// Pairing
+export { startDevicePairing, completeDevicePairing, PAIR_PREFIX } from './sync/pairing.js';
+export type { PairResult } from './sync/pairing.js';
+
+// Pull cache
+export { pullCache, PULL_CACHE_MAX_AGE_MS } from './sync/pull-cache.js';
+
+// Profile cache
+export { cacheProfile, loadCachedProfile } from './sync/profile-cache.js';
+
+// Fetch
+export { fetchWithTimeout, CONNECT_TIMEOUT_MS } from './sync/fetch-timeout.js';
+
+// Base64
+export { starfishBase64 } from './sync/base64.js';
+export { toBase64Url, fromBase64Url } from './sync/base64url.js';

package/src/objects/objects.test.ts

@@ -0,0 +1,288 @@
+import { describe, it, expect } from 'vitest';
+import type { ObjectNode } from '../core/types.js';
+import {
+  addObject,
+  archiveObject,
+  breadcrumbs,
+  buildTree,
+  ancestors,
+  categoryId,
+  DEFAULT_CATEGORY,
+  nextOrder,
+  patchObject,
+  reparentObject,
+  reorderObjects,
+  seedIndexNodes,
+  subtreeIds,
+  objectsToRoomCategories,
+  excludeAutomatedRooms,
+  roomKindToSubtype,
+  subtypeToRoomKind,
+} from './objects.js';
+
+const NOW = 1_700_000_000_000;
+
+function makeNode(overrides: Partial<ObjectNode> = {}): ObjectNode {
+  return {
+    id: 'n1',
+    type: 'room',
+    parentId: null,
+    order: 1,
+    title: 'Test',
+    updatedAt: NOW,
+    ...overrides,
+  };
+}
+
+describe('DEFAULT_CATEGORY', () => {
+  it('is CHANNELS', () => { expect(DEFAULT_CATEGORY).toBe('CHANNELS'); });
+});
+
+describe('categoryId', () => {
+  it('is deterministic for the same name', () => {
+    expect(categoryId('Channels')).toBe(categoryId('Channels'));
+  });
+  it('differs for different names', () => {
+    expect(categoryId('Alpha')).not.toBe(categoryId('Beta'));
+  });
+  it('starts with cat-', () => {
+    expect(categoryId('test')).toMatch(/^cat-/);
+  });
+});
+
+describe('nextOrder', () => {
+  it('returns 1 for empty sibling list', () => {
+    expect(nextOrder([])).toBe(1);
+  });
+  it('returns max+1', () => {
+    const siblings = [makeNode({ order: 3 }), makeNode({ id: 'n2', order: 7 })];
+    expect(nextOrder(siblings)).toBe(8);
+  });
+});
+
+describe('buildTree', () => {
+  it('builds a flat list for root nodes', () => {
+    const nodes: ObjectNode[] = [
+      makeNode({ id: 'a', order: 1 }),
+      makeNode({ id: 'b', order: 2 }),
+    ];
+    const tree = buildTree(nodes);
+    expect(tree).toHaveLength(2);
+    expect(tree[0].id).toBe('a');
+    expect(tree[1].id).toBe('b');
+  });
+
+  it('nests children under their parent', () => {
+    const nodes: ObjectNode[] = [
+      makeNode({ id: 'cat', type: 'category', parentId: null, order: 1 }),
+      makeNode({ id: 'room', type: 'room', parentId: 'cat', order: 1 }),
+    ];
+    const tree = buildTree(nodes);
+    expect(tree).toHaveLength(1);
+    expect(tree[0].children).toHaveLength(1);
+    expect(tree[0].children[0].id).toBe('room');
+  });
+
+  it('excludes archived nodes by default', () => {
+    const nodes: ObjectNode[] = [
+      makeNode({ id: 'a', archived: true }),
+      makeNode({ id: 'b' }),
+    ];
+    const tree = buildTree(nodes);
+    expect(tree).toHaveLength(1);
+    expect(tree[0].id).toBe('b');
+  });
+
+  it('repairs orphans (parentId missing) → reparents to root', () => {
+    const nodes: ObjectNode[] = [
+      makeNode({ id: 'orphan', parentId: 'nonexistent' }),
+    ];
+    const tree = buildTree(nodes);
+    expect(tree).toHaveLength(1);
+    expect(tree[0].id).toBe('orphan');
+  });
+
+  it('repairs cycles → reparents cycle node to root', () => {
+    // a → b → a is a cycle; both should appear at root without infinite loop
+    const nodes: ObjectNode[] = [
+      makeNode({ id: 'a', parentId: 'b', order: 1 }),
+      makeNode({ id: 'b', parentId: 'a', order: 2 }),
+    ];
+    const tree = buildTree(nodes);
+    expect(tree.length).toBeGreaterThan(0);
+  });
+});
+
+describe('breadcrumbs + ancestors', () => {
+  const nodes: ObjectNode[] = [
+    makeNode({ id: 'root', parentId: null, order: 1 }),
+    makeNode({ id: 'child', parentId: 'root', order: 1 }),
+    makeNode({ id: 'grandchild', parentId: 'child', order: 1 }),
+  ];
+
+  it('breadcrumbs returns root→self', () => {
+    const trail = breadcrumbs(nodes, 'grandchild');
+    expect(trail.map(n => n.id)).toEqual(['root', 'child', 'grandchild']);
+  });
+
+  it('ancestors returns root→parent (exclusive)', () => {
+    const trail = ancestors(nodes, 'grandchild');
+    expect(trail.map(n => n.id)).toEqual(['root', 'child']);
+  });
+});
+
+describe('subtreeIds', () => {
+  const nodes: ObjectNode[] = [
+    makeNode({ id: 'root', parentId: null }),
+    makeNode({ id: 'child1', parentId: 'root' }),
+    makeNode({ id: 'child2', parentId: 'root' }),
+    makeNode({ id: 'grandchild', parentId: 'child1' }),
+  ];
+
+  it('includes self and all descendants', () => {
+    const ids = subtreeIds(nodes, 'root');
+    expect([...ids].sort()).toEqual(['child1', 'child2', 'grandchild', 'root'].sort());
+  });
+});
+
+describe('addObject', () => {
+  it('appends a new node with correct order', () => {
+    const { nodes, node } = addObject([], { type: 'room', title: 'general' }, NOW);
+    expect(nodes).toHaveLength(1);
+    expect(node.title).toBe('general');
+    expect(node.type).toBe('room');
+    expect(node.order).toBe(1);
+  });
+
+  it('respects provided id', () => {
+    const { node } = addObject([], { id: 'my-id', type: 'category', title: 'Channels' }, NOW);
+    expect(node.id).toBe('my-id');
+  });
+});
+
+describe('patchObject', () => {
+  it('updates title and bumps updatedAt', () => {
+    const nodes = [makeNode({ id: 'x', title: 'old', updatedAt: 0 })];
+    const patched = patchObject(nodes, 'x', { title: 'new' }, NOW);
+    expect(patched[0].title).toBe('new');
+    expect(patched[0].updatedAt).toBe(NOW);
+  });
+});
+
+describe('reparentObject', () => {
+  it('moves a node to a new parent', () => {
+    const nodes: ObjectNode[] = [
+      makeNode({ id: 'cat-a', type: 'category', parentId: null }),
+      makeNode({ id: 'cat-b', type: 'category', parentId: null }),
+      makeNode({ id: 'room', type: 'room', parentId: 'cat-a' }),
+    ];
+    const result = reparentObject(nodes, 'room', 'cat-b', NOW);
+    const room = result.find(n => n.id === 'room')!;
+    expect(room.parentId).toBe('cat-b');
+  });
+
+  it('rejects making a node its own descendant', () => {
+    const nodes: ObjectNode[] = [
+      makeNode({ id: 'parent', type: 'category', parentId: null }),
+      makeNode({ id: 'child', type: 'room', parentId: 'parent' }),
+    ];
+    const result = reparentObject(nodes, 'parent', 'child', NOW);
+    expect(result).toBe(nodes); // unchanged
+  });
+});
+
+describe('reorderObjects', () => {
+  it('applies explicit order values', () => {
+    const nodes = [makeNode({ id: 'x', order: 1 }), makeNode({ id: 'y', order: 2 })];
+    const result = reorderObjects(nodes, { x: 5, y: 3 }, NOW);
+    const x = result.find(n => n.id === 'x')!;
+    const y = result.find(n => n.id === 'y')!;
+    expect(x.order).toBe(5);
+    expect(y.order).toBe(3);
+  });
+});
+
+describe('archiveObject', () => {
+  it('archives a node and its subtree', () => {
+    const nodes: ObjectNode[] = [
+      makeNode({ id: 'parent', parentId: null }),
+      makeNode({ id: 'child', parentId: 'parent' }),
+    ];
+    const result = archiveObject(nodes, 'parent', NOW);
+    expect(result.find(n => n.id === 'parent')!.archived).toBe(true);
+    expect(result.find(n => n.id === 'child')!.archived).toBe(true);
+  });
+});
+
+describe('seedIndexNodes', () => {
+  it('creates category + room nodes', () => {
+    const nodes = seedIndexNodes([{ id: 'r1', name: 'general', kind: 'channel', category: 'CHANNELS' }], NOW);
+    expect(nodes.some(n => n.type === 'category')).toBe(true);
+    expect(nodes.some(n => n.type === 'room')).toBe(true);
+  });
+
+  it('dedupes categories', () => {
+    const rooms = [
+      { id: 'r1', name: 'general', kind: 'channel' as const, category: 'CHANNELS' },
+      { id: 'r2', name: 'random', kind: 'channel' as const, category: 'CHANNELS' },
+    ];
+    const nodes = seedIndexNodes(rooms, NOW);
+    const cats = nodes.filter(n => n.type === 'category');
+    expect(cats).toHaveLength(1);
+  });
+});
+
+describe('roomKindToSubtype / subtypeToRoomKind', () => {
+  it('channel ↔ channel', () => {
+    expect(roomKindToSubtype('channel')).toBe('channel');
+    expect(subtypeToRoomKind('channel')).toBe('channel');
+  });
+  it('dm ↔ dm', () => {
+    expect(roomKindToSubtype('dm')).toBe('dm');
+    expect(subtypeToRoomKind('dm')).toBe('dm');
+  });
+  it('automated ↔ automation', () => {
+    expect(roomKindToSubtype('automated')).toBe('automation');
+    expect(subtypeToRoomKind('automation')).toBe('automated');
+  });
+});
+
+describe('objectsToRoomCategories', () => {
+  it('returns null for empty index', () => {
+    expect(objectsToRoomCategories([], 'sp-1', 'CHANNELS')).toBeNull();
+  });
+
+  it('groups rooms under their category', () => {
+    const nodes: ObjectNode[] = [
+      makeNode({ id: 'cat', type: 'category', parentId: null, order: 1, title: 'CHANNELS' }),
+      makeNode({ id: 'room', type: 'room', parentId: 'cat', order: 1, title: 'general' }),
+    ];
+    const cats = objectsToRoomCategories(nodes, 'sp-1', 'CHANNELS')!;
+    expect(cats).toHaveLength(1);
+    expect(cats[0].name).toBe('CHANNELS');
+    expect(cats[0].rooms[0].name).toBe('general');
+  });
+});
+
+describe('excludeAutomatedRooms', () => {
+  it('removes categories that held ONLY automated rooms', () => {
+    const cats = [{ name: 'C', rooms: [{ id: 'r', spaceId: 's', category: 'C', name: 'bot', kind: 'automated' as const }] }];
+    const result = excludeAutomatedRooms(cats);
+    // A category whose ONLY room was automated gets dropped entirely.
+    expect(result).toHaveLength(0);
+  });
+
+  it('keeps categories that still have non-automated rooms', () => {
+    const cats = [{
+      name: 'C',
+      rooms: [
+        { id: 'r1', spaceId: 's', category: 'C', name: 'bot', kind: 'automated' as const },
+        { id: 'r2', spaceId: 's', category: 'C', name: 'general', kind: 'channel' as const },
+      ],
+    }];
+    const result = excludeAutomatedRooms(cats);
+    expect(result).toHaveLength(1);
+    expect(result[0].rooms).toHaveLength(1);
+    expect(result[0].rooms[0].name).toBe('general');
+  });
+});