@abraca/dabra 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -132,8 +132,129 @@ declare class EventEmitter {
   removeAllListeners(): void;
 }
 //#endregion
+//#region packages/provider/src/AbracadabraClient.d.ts
+interface AbracadabraClientConfig {
+  /** Server base URL (http or https). WebSocket URL is derived automatically. */
+  url: string;
+  /** Initial JWT token. If omitted and persistAuth is true, loads from storage. */
+  token?: string;
+  /** Persist JWT to localStorage for stay-logged-in. Default: true in browser. */
+  persistAuth?: boolean;
+  /** localStorage key for token persistence. Default: "abracadabra:auth". */
+  storageKey?: string;
+  /** Custom fetch implementation (useful for Node.js or testing). */
+  fetch?: typeof globalThis.fetch;
+}
+declare class AbracadabraClient {
+  private _token;
+  private readonly baseUrl;
+  private readonly persistAuth;
+  private readonly storageKey;
+  private readonly _fetch;
+  constructor(config: AbracadabraClientConfig);
+  get token(): string | null;
+  set token(value: string | null);
+  get isAuthenticated(): boolean;
+  /** Derives ws:// or wss:// URL from the http(s) base URL. */
+  get wsUrl(): string;
+  /** Register a new user with password. */
+  register(opts: {
+    username: string;
+    password: string;
+    email?: string;
+    displayName?: string;
+  }): Promise<UserProfile>;
+  /**
+   * Register a new user with an Ed25519 public key (crypto auth).
+   * Username is optional — if omitted, a short identifier is derived from the key.
+   */
+  registerWithKey(opts: {
+    publicKey: string;
+    username?: string;
+    deviceName?: string;
+    displayName?: string;
+    email?: string;
+  }): Promise<UserProfile>;
+  /** Login with username + password. Auto-persists returned token. */
+  login(opts: {
+    username: string;
+    password: string;
+  }): Promise<string>;
+  /** Request an Ed25519 crypto auth challenge for the given public key. */
+  challenge(publicKey: string): Promise<{
+    challenge: string;
+    expiresAt: number;
+  }>;
+  /** Verify an Ed25519 signature to complete crypto auth. Auto-persists token. */
+  verify(opts: {
+    publicKey: string;
+    signature: string;
+    challenge: string;
+  }): Promise<string>;
+  /**
+   * Full crypto auth flow: challenge → sign → verify.
+   * Convenience method combining challenge() + external signing + verify().
+   */
+  loginWithKey(publicKey: string, signChallenge: (challenge: string) => Promise<string>): Promise<string>;
+  /** Add a new Ed25519 public key to the current user (multi-device). */
+  addKey(opts: {
+    publicKey: string;
+    deviceName?: string;
+  }): Promise<void>;
+  /** List all registered public keys for the current user. */
+  listKeys(): Promise<PublicKeyInfo[]>;
+  /** Revoke a public key by its ID. */
+  revokeKey(keyId: string): Promise<void>;
+  /** Clear token from memory and storage. */
+  logout(): void;
+  /** Get the current user's profile. */
+  getMe(): Promise<UserProfile>;
+  /** Update the current user's display name. */
+  updateMe(opts: {
+    displayName?: string;
+  }): Promise<void>;
+  /** Create a new root document. Returns its metadata. */
+  createDoc(opts?: {
+    id?: string;
+  }): Promise<DocumentMeta>;
+  /** Get document metadata. */
+  getDoc(docId: string): Promise<DocumentMeta>;
+  /** Delete a document (requires Owner role). Cascades to children and uploads. */
+  deleteDoc(docId: string): Promise<void>;
+  /** List immediate child documents. */
+  listChildren(docId: string): Promise<string[]>;
+  /** Create a child document under a parent (requires write permission). */
+  createChild(docId: string, opts?: {
+    child_id?: string;
+  }): Promise<DocumentMeta>;
+  /** Grant or change a user's role on a document (requires Owner). */
+  setPermission(docId: string, opts: {
+    user_id: string;
+    role: "owner" | "editor" | "viewer" | "observer";
+  }): Promise<void>;
+  /** Revoke a user's permission on a document (requires Owner). */
+  removePermission(docId: string, opts: {
+    user_id: string;
+  }): Promise<void>;
+  /** Upload a file to a document (requires write permission). */
+  upload(docId: string, file: File | Blob, filename?: string): Promise<UploadMeta>;
+  /** List all uploads for a document. */
+  listUploads(docId: string): Promise<UploadInfo[]>;
+  /** Download an upload as a Blob. */
+  getUpload(docId: string, uploadId: string): Promise<Blob>;
+  /** Delete an upload (requires uploader or document Owner). */
+  deleteUpload(docId: string, uploadId: string): Promise<void>;
+  /** Health check — no auth required. */
+  health(): Promise<HealthStatus>;
+  private request;
+  private toError;
+  private loadPersistedToken;
+  private persistToken;
+  private clearPersistedToken;
+}
+//#endregion
 //#region packages/provider/src/AbracadabraProvider.d.ts
-interface AbracadabraProviderConfiguration extends HocuspocusProviderConfiguration {
+interface AbracadabraProviderConfiguration extends Omit<HocuspocusProviderConfiguration, "url" | "websocketProvider"> {
   /**
    * Subdocument loading strategy.
    * - "lazy"  (default) – child providers are created only when explicitly requested.
@@ -159,6 +280,16 @@ interface AbracadabraProviderConfiguration extends HocuspocusProviderConfigurati
    * Required when cryptoIdentity is set.
    */
   signChallenge?: (challenge: string) => Promise<string>;
+  /**
+   * AbracadabraClient instance for REST API access.
+   * When provided, the provider automatically derives the WebSocket URL
+   * and token from the client (unless explicitly overridden).
+   */
+  client?: AbracadabraClient;
+  /** WebSocket URL. Derived from client.wsUrl if client is provided. */
+  url?: string;
+  /** Shared WebSocket connection (use when multiplexing multiple root documents). */
+  websocketProvider?: HocuspocusProviderWebsocket;
 }
 /**
  * AbracadabraProvider extends HocuspocusProvider with:
@@ -177,6 +308,7 @@ interface AbracadabraProviderConfiguration extends HocuspocusProviderConfigurati
  */
 declare class AbracadabraProvider extends HocuspocusProvider {
   effectiveRole: EffectiveRole;
+  private _client;
   private offlineStore;
   private childProviders;
   private subdocLoading;
@@ -185,14 +317,20 @@ declare class AbracadabraProvider extends HocuspocusProvider {
   constructor(configuration: AbracadabraProviderConfiguration);
   authenticatedHandler(scope: string): void;
   /**
-   * Override sendToken to send an identity declaration instead of a JWT
-   * when cryptoIdentity is configured.
+   * Override sendToken to send a pubkey-only identity declaration instead of a
+   * JWT when cryptoIdentity is configured.
+   *
+   * The public key is the sole identifier in the crypto auth handshake.
+   * Username is decoupled from auth; it lives on the server as an immutable
+   * internal field and is never sent in the challenge-response frames.
    */
   sendToken(): Promise<void>;
   /** Handle an auth_challenge message from the server. */
   private handleAuthChallenge;
   private restorePermissionSnapshot;
   get canWrite(): boolean;
+  /** The AbracadabraClient instance for REST API access, if configured. */
+  get client(): AbracadabraClient | null;
   /**
    * Called when a MSG_STATELESS frame arrives from the server.
    * Abracadabra uses stateless frames to deliver subdoc confirmations
@@ -418,10 +556,15 @@ type StatesArray = {
   [key: string | number]: any;
 }[];
 type EffectiveRole = "owner" | "editor" | "viewer" | null;
-/** Ed25519 identity for passwordless crypto auth (Model B multi-key). */
+/**
+ * Ed25519 identity for passwordless crypto auth.
+ *
+ * The public key is the sole identifier sent to the server during the
+ * challenge-response handshake. Username is decoupled from auth and is
+ * managed separately as a mutable display name (see PATCH /users/me).
+ */
 interface CryptoIdentity {
-  username: string;
-  /** base64url-encoded Ed25519 public key (32 bytes) */
+  /** base64url-encoded Ed25519 public key (32 bytes). Primary auth identifier. */
   publicKey: string;
 }
 interface SubdocRegisteredEvent {
@@ -436,6 +579,38 @@ type onSubdocLoadedParameters = {
 interface AbracadabraOutgoingMessageArguments extends OutgoingMessageArguments {
   childDocumentName: string;
 }
+interface UserProfile {
+  id: string;
+  username: string;
+  email: string | null;
+  displayName: string | null;
+}
+interface DocumentMeta {
+  id: string;
+  parent_id: string | null;
+}
+interface UploadMeta {
+  id: string;
+  doc_id: string;
+  filename: string;
+}
+interface UploadInfo {
+  id: string;
+  filename: string;
+  mime_type: string;
+  size: number;
+}
+interface PublicKeyInfo {
+  id: string;
+  publicKey: string;
+  deviceName: string | null;
+  revoked: boolean;
+}
+interface HealthStatus {
+  status: string;
+  version: string;
+  active_documents: number;
+}
 //#endregion
 //#region packages/provider/src/HocuspocusProviderWebsocket.d.ts
 type HocuspocusWebSocket = WebSocket & {
@@ -768,7 +943,13 @@ declare class CryptoIdentityKeystore {
   sign(challengeB64: string): Promise<string>;
   /** Returns the stored base64url public key, or null if no identity exists. */
   getPublicKey(): Promise<string | null>;
-  /** Returns the stored username, or null if no identity exists. */
+  /**
+   * Returns the locally-stored internal username label, or null if no identity exists.
+   *
+   * This is NOT the auth identifier (the public key is). It can be used as a
+   * hint when calling POST /auth/register, or displayed before the user sets
+   * a real display name via PATCH /users/me.
+   */
   getUsername(): Promise<string | null>;
   /** Returns true if an identity is stored in IndexedDB. */
   hasIdentity(): Promise<boolean>;
@@ -776,4 +957,4 @@ declare class CryptoIdentityKeystore {
   clear(): Promise<void>;
 }
 //#endregion
-export { AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AuthorizedScope, AwarenessError, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, EffectiveRole, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PendingSubdoc, StatesArray, SubdocMessage, SubdocRegisteredEvent, WebSocketStatus, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters };
+export { AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AuthorizedScope, AwarenessError, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, DocumentMeta, EffectiveRole, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PendingSubdoc, PublicKeyInfo, StatesArray, SubdocMessage, SubdocRegisteredEvent, UploadInfo, UploadMeta, UserProfile, WebSocketStatus, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",