@evolu/common 6.0.1-preview.8 → 7.0.0

package/dist/src/Evolu/Owner.d.ts

@@ -1,160 +1,313 @@
+import { NonEmptyReadonlyArray } from "../Array.js";
+import { EncryptionKey, RandomBytesDep } from "../Crypto.js";
+import { Mnemonic, NonNegativeInt } from "../Type.js";
+import { TimestampBytes } from "./Timestamp.js";
 /**
- * TODO:
+ * The Owner represents ownership of data in Evolu. Every database change is
+ * assigned to an owner, enabling sync functionality and access control.
  *
- * @module
- */
-import { CreateMnemonicDep, CreateRandomBytesDep, EncryptionKey, MnemonicSeed } from "../Crypto.js";
-import { NanoIdLibDep } from "../NanoId.js";
-import { TimeDep } from "../Time.js";
-import { DateIsoString, Mnemonic, NonNegativeInt } from "../Type.js";
-import { TimestampString } from "./Timestamp.js";
-/**
- * `Owner` is an entity in Evolu that owns data, meaning it is locally stored on
- * a device under the user’s control. Data can be personal private, peer-to-peer
- * shared, or aggregated from multiple owners.
- *
- * An owner has a {@link Mnemonic} from which {@link OwnerId} and
- * {@link EncryptionKey} are deterministically derived using SLIP-21, and an
- * optional {@link WriteKey} that, when present, enables writing to the Evolu
- * Relay or peers. The {@link WriteKey} can be rotated.
- *
- * Variants include {@link AppOwner}, {@link ShardOwner}, {@link SharedOwner}, and
- * {@link SharedReadonlyOwner}, each with specific roles and properties detailed
- * in their respective definitions.
- *
- * Public-key cryptography isn’t included here as it belongs to app and varies
- * by use case. An Evolu app without collaboration doesn’t need it, while a
- * Nostr-like app can leverage Nostr NIPs, or a super-safe app can use
- * post-quantum cryptography.
+ * Owners enable **partial sync** - applications can choose which owners to
+ * sync, allowing selective data synchronization based on specific needs.
+ *
+ * Owners also provide **real data deletion** - while individual changes in
+ * local-first/distributed systems can only be marked as deleted, entire owners
+ * can be completely deleted from both relays and devices (except for
+ * {@link AppOwner}, which must be preserved for sync coordination).
+ *
+ * Evolu provides different owner types depending on their use case:
+ *
+ * - **Coordination**: {@link AppOwner} for sync coordination and long-term
+ *   persistence
+ * - **Data partitioning**: {@link ShardOwner} for partitioning application data
+ * - **Collaboration**: {@link SharedOwner} for collaborative write access
+ * - **Data sharing**: {@link SharedReadonlyOwner} for read-only access to shared
+ *   data
+ *
+ * Owners are cryptographically derived from an {@link OwnerSecret} using
+ * SLIP-21, ensuring secure and deterministic key generation:
+ *
+ * - {@link OwnerId}: Globally unique public identifier
+ * - {@link EncryptionKey}: Symmetric encryption key for data protection
+ * - {@link OwnerWriteKey}: Authentication token for write operations (rotatable)
+ *
+ * @see {@link createOwner}
  */
 export interface Owner {
-    readonly mnemonic: Mnemonic;
-    readonly createdAt: DateIsoString;
     readonly id: OwnerId;
-    readonly encryptionKey: EncryptionKey;
-    readonly writeKey: WriteKey;
-}
-export interface OwnerWithWriteAccess {
-    readonly id: OwnerId;
-    readonly encryptionKey: EncryptionKey;
-    readonly writeKey: WriteKey;
+    readonly encryptionKey: OwnerEncryptionKey;
+    readonly writeKey: OwnerWriteKey;
 }
 /**
- * The unique identifier of {@link Owner} derived from the {@link Mnemonic}.
- *
- * This branded {@link Id} type, generated by {@link createSlip21Id}, is a
- * 21-character {@link Base64Url} string (126 bits of entropy), providing a
- * compact, shareable, and secure identifier for UI use, tied to the owner's
- * mnemonic and derivation path.
+ * OwnerId is a branded {@link Id} that uniquely identifies an {@link Owner}.
+ * Branded from {@link Id} to leverage existing helpers like {@link idToIdBytes}.
  */
-export declare const OwnerId: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "Id", import("../Type.js").RegexError<"Id">, import("../Type.js").StringError>, "OwnerId", import("../Type.js").BrandWithoutRefineError<"OwnerId", import("../Type.js").StringError | import("../Type.js").RegexError<"Id">>, never>;
+export declare const OwnerId: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "Id", import("../Type.js").IdError, import("../Type.js").StringError>, "OwnerId", import("../Type.js").BrandWithoutRefineError<"OwnerId", import("../Type.js").StringError | import("../Type.js").IdError>, never>;
 export type OwnerId = typeof OwnerId.Type;
-export declare const writeKeyLength: NonNegativeInt;
+/** Bytes representation of {@link OwnerId}. */
+export declare const OwnerIdBytes: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError>, "Length16", import("../Type.js").LengthError<16>, import("../Type.js").Uint8ArrayError>, "IdBytes", import("../Type.js").BrandWithoutRefineError<"IdBytes", import("../Type.js").LengthError<16> | import("../Type.js").Uint8ArrayError>, never>, "OwnerIdBytes", import("../Type.js").BrandWithoutRefineError<"OwnerIdBytes", import("../Type.js").BrandWithoutRefineError<"IdBytes", import("../Type.js").LengthError<16> | import("../Type.js").Uint8ArrayError>>, never>;
+export type OwnerIdBytes = typeof OwnerIdBytes.Type;
+export declare const ownerIdToOwnerIdBytes: (ownerId: OwnerId) => OwnerIdBytes;
+export declare const ownerIdBytesToOwnerId: (ownerIdBytes: OwnerIdBytes) => OwnerId;
+export declare const ownerWriteKeyLength: number & import("../Brand.js").Brand<"Int"> & import("../Brand.js").Brand<"NonNegative">;
+export declare const OwnerEncryptionKey: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", Uint8Array<ArrayBufferLike> & import("../Brand.js").Brand<"Entropy">, Uint8Array<ArrayBufferLike>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>, Uint8Array<ArrayBufferLike>, never>, "Length32", import("../Type.js").LengthError<32>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, "EncryptionKey", import("../Type.js").BrandWithoutRefineError<"EncryptionKey", import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError> | import("../Type.js").LengthError<32>>, never>, "OwnerEncryptionKey", import("../Type.js").BrandWithoutRefineError<"OwnerEncryptionKey", import("../Type.js").BrandWithoutRefineError<"EncryptionKey", import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError> | import("../Type.js").LengthError<32>>>, never>;
+export type OwnerEncryptionKey = typeof OwnerEncryptionKey.Type;
 /**
- * A secure token proving the initiator can write changes. Derived from a
- * mnemonic or randomly generated. It's rotatable.
+ * A secure token for write operations. It's derived from {@link OwnerSecret} by
+ * default and can be rotated via {@link createOwnerWriteKey}.
  */
-export declare const WriteKey: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError>, `Length${number & import("../Types.js").Brand<"Int"> & import("../Types.js").Brand<"NonNegative">}`, import("../Type.js").LengthError<number & import("../Types.js").Brand<"Int"> & import("../Types.js").Brand<"NonNegative">>, import("../Type.js").Uint8ArrayError>, "WriteKey", import("../Type.js").BrandWithoutRefineError<"WriteKey", import("../Type.js").Uint8ArrayError | import("../Type.js").LengthError<number & import("../Types.js").Brand<"Int"> & import("../Types.js").Brand<"NonNegative">>>, never>;
-export type WriteKey = typeof WriteKey.Type;
+export declare const OwnerWriteKey: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", Uint8Array<ArrayBufferLike> & import("../Brand.js").Brand<"Entropy">, Uint8Array<ArrayBufferLike>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>, Uint8Array<ArrayBufferLike>, never>, "Length16", import("../Type.js").LengthError<16>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, "OwnerWriteKey", import("../Type.js").BrandWithoutRefineError<"OwnerWriteKey", import("../Type.js").LengthError<16> | import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, never>;
+export type OwnerWriteKey = typeof OwnerWriteKey.Type;
 /**
- * The root owner of an Evolu app, created from a mnemonic safely generated on a
- * device when the app is initialized or restored on another device using an
- * existing mnemonic. It manages the app's core data, including the storage of
- * other owners' mnemonics in an encrypted app table. Its `writeKey` is
- * deterministic and rotatable. Never share the AppOwner mnemonic with anyone.
+ * 32 bytes of cryptographic entropy used to derive {@link Owner} keys.
+ *
+ * Can be created using {@link createOwnerSecret} or converted from a
+ * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
+ */
+export declare const OwnerSecret: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", Uint8Array<ArrayBufferLike> & import("../Brand.js").Brand<"Entropy">, Uint8Array<ArrayBufferLike>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>, Uint8Array<ArrayBufferLike>, never>, "Length32", import("../Type.js").LengthError<32>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, "OwnerSecret", import("../Type.js").BrandWithoutRefineError<"OwnerSecret", import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError> | import("../Type.js").LengthError<32>>, never>;
+export type OwnerSecret = typeof OwnerSecret.Type;
+/** Creates a {@link OwnerSecret}. */
+export declare const createOwnerSecret: (deps: RandomBytesDep) => OwnerSecret;
+/** Converts an {@link OwnerSecret} to a {@link Mnemonic}. */
+export declare const ownerSecretToMnemonic: (secret: OwnerSecret) => Mnemonic;
+/** Converts a {@link Mnemonic} to an {@link OwnerSecret}. */
+export declare const mnemonicToOwnerSecret: (mnemonic: Mnemonic) => OwnerSecret;
+/** Creates a randomly generated {@link OwnerWriteKey}. */
+export declare const createOwnerWriteKey: (deps: RandomBytesDep) => OwnerWriteKey;
+/**
+ * Creates an {@link Owner} from a {@link OwnerSecret} using SLIP-21 key
+ * derivation.
+ *
+ * This is an internal helper function, use:
+ *
+ * - {@link createAppOwner}
+ * - {@link createShardOwner}
+ * - {@link createSharedOwner}
+ * - {@link createSharedReadonlyOwner}
+ */
+export declare const createOwner: (secret: OwnerSecret) => Owner;
+/**
+ * The AppOwner represents the application owner. It's created using a
+ * cryptographically secure random generator or derived from an external source,
+ * e.g., mnemonic stored securely in a hardware device.
+ *
+ * While it's possible to store all application data in AppOwner, the better
+ * approach is to use it only for sync coordination. Storing all app data in
+ * AppOwner means that data will be stored/synced forever. And that's a problem
+ * if we want to provide real data deletion or in-app data migration without
+ * data duplication. In local-first apps/distributed systems, we can't delete
+ * individual changes, we only mark them as deleted, otherwise sync could not
+ * work.
+ *
+ * If we really want to delete data or at least avoid syncing it, we must store
+ * it using a different owner than AppOwner, e.g. {@link ShardOwner} or
+ * {@link SharedOwner}, and delete that owner. The AppOwner itself must be
+ * preserved because it coordinates deletion information across devices. Other
+ * devices need to sync the information that an owner was deleted so they can
+ * delete their local data as well.
+ *
+ * ### Privacy Considerations
+ *
+ * AppOwner must never be shared with anyone, except for its {@link OwnerId},
+ * which can be used for authorization with
+ * {@link createOwnerWebSocketTransport}. It's safe because OwnerId is
+ * pseudonymous (it can't be assigned to a specific person).
+ *
+ * For data sharing scenarios, use {@link SharedOwner} and
+ * {@link SharedReadonlyOwner} instead, which are designed specifically for
+ * collaborative access.
  */
 export interface AppOwner extends Owner {
     readonly type: "AppOwner";
+    /**
+     * The mnemonic that was used to derive the AppOwner keys. Optional when the
+     * AppOwner is created from external keys to avoid sharing the mnemonic with
+     * the Evolu app.
+     */
+    readonly mnemonic?: Mnemonic | null;
 }
+/** Creates an {@link AppOwner} from an {@link OwnerSecret}. */
+export declare const createAppOwner: (secret: OwnerSecret) => AppOwner;
 /**
- * Used to shard data within an app for partial or deferred sync. Created in the
- * Evolu `initialData` function or dynamically as needed. Its mnemonic is stored
- * in an app table (encrypted by `AppOwner`) and synced between devices. Its
- * `writeKey` is deterministic and rotatable, enabling selective syncing of data
- * subsets. Not intended for sharing outside the app.
- *
- * This type omits `id`, `encryptionKey`, and `createdAt` as they are derived by
- * Evolu from the `mnemonic`, reducing storage overhead.
+ * An {@link Owner} for sharding data.
+ *
+ * ShardOwners are the recommended storage location for most application data
+ * because they can be completely deleted (both on relays and devices) and
+ * conditionally synced.
+ *
+ * Can be created from {@link OwnerSecret} via {@link createShardOwner} or
+ * deterministically derived from {@link AppOwner} using
+ * {@link deriveShardOwner}.
  */
-export interface ShardOwner {
+export interface ShardOwner extends Owner {
     readonly type: "ShardOwner";
-    readonly mnemonic: Mnemonic;
-    readonly writeKey: WriteKey;
+    readonly transports?: ReadonlyArray<OwnerTransport>;
 }
+/** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
+export declare const createShardOwner: (secret: OwnerSecret, transports?: ReadonlyArray<OwnerTransport>) => ShardOwner;
 /**
- * Used to share data among one or more users, enabling collaboration or
- * controlled access. Its `writeKey` is random (not derived from the mnemonic,
- * stored alongside it in the app table) and rotatable, ensuring it cannot be
- * regenerated by others if shared. Share the `mnemonic` alone for read-only
- * access (as `SharedReadonlyOwner`) or share SharedOwner itself for write
- * access.
- *
- * This type omits `id`, `encryptionKey`, and `createdAt` as they are derived by
- * Evolu from the `mnemonic`, reducing storage overhead.
+ * Derives a {@link ShardOwner} from an {@link AppOwner} using the specified path.
+ *
+ * **Advantages of derived owners:**
+ *
+ * - **Deterministic**: Same path always produces the same ShardOwner across all
+ *   devices
+ * - **Immediate availability**: Can be hardcoded and used before sync occurs
+ * - **Consistent setup**: All devices start with identical data structure
+ * - **Lifecycle management**: Can implement epoch patterns for clean data
+ *   deletion and recreation
+ *
+ * **Common patterns:**
+ *
+ * - Use paths like `["shard", 1]` for versioned data lifecycle
+ * - Use paths like `["project", "MyApp", 1]` for named partitions with versions
+ * - Each device can derive the same owners and set up initial structure
  */
-export interface SharedOwner {
+export declare const deriveShardOwner: (owner: AppOwner, path: NonEmptyReadonlyArray<string | number>, transports?: ReadonlyArray<OwnerTransport>) => ShardOwner;
+/** An {@link Owner} for collaborative data with write access. */
+export interface SharedOwner extends Owner {
     readonly type: "SharedOwner";
-    readonly mnemonic: Mnemonic;
-    readonly writeKey: WriteKey;
+    readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 /**
- * Used for sharing data that can only be read, such as with followers or peers
- * in a read-only sync scenario. It lacks a `writeKey`, containing only the
- * `mnemonic` from which `id` and `encryptionKey` are derived by Evolu.
- * Typically derived from a `SharedOwner` by sharing its `mnemonic` without the
- * `writeKey`.
+ * Creates a {@link SharedOwner} from an {@link OwnerSecret} for collaborative
+ * write access.
+ *
+ * Use {@link createSharedReadonlyOwner} to create a read-only version for
+ * sharing.
+ */
+export declare const createSharedOwner: (secret: OwnerSecret, transports?: ReadonlyArray<OwnerTransport>) => SharedOwner;
+/**
+ * Read-only version of a {@link SharedOwner} for data sharing. Contains only the
+ * {@link OwnerId} and {@link EncryptionKey} needed for others to read the shared
+ * data without write access.
  */
 export interface SharedReadonlyOwner {
     readonly type: "SharedReadonlyOwner";
-    readonly mnemonic: Mnemonic;
+    readonly id: OwnerId;
+    readonly encryptionKey: EncryptionKey;
+    readonly transports?: ReadonlyArray<OwnerTransport>;
 }
+/** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
+export declare const createSharedReadonlyOwner: (sharedOwner: SharedOwner) => SharedReadonlyOwner;
 /**
- * Creates an {@link AppOwner}, optionally from an existing mnemonic to restore
- * it on another device; otherwise, generates a new mnemonic.
- */
-export declare const createAppOwner: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) => (mnemonic?: string & import("../Types.js").Brand<"Trimmed"> & import("../Types.js").Brand<"MinLength1"> & import("../Types.js").Brand<"Mnemonic">) => AppOwner;
-/**
- * Creates a {@link ShardOwner} for sharding app data with a freshly generated
- * mnemonic. Unlike {@link createAppOwner}, it doesn’t accept an existing
- * mnemonic because ShardOwner mnemonics are always generated and restored
- * automatically via database sync.
- */
-export declare const createShardOwner: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) => ShardOwner;
-/**
- * Creates a fresh {@link SharedOwner} for sharing data with write access. Takes
- * no arguments as both `mnemonic` and rotatable `writeKey` are newly generated;
- * when shared, recipients use the provided `mnemonic` and `writeKey` directly
- * as a {@link SharedOwner} without needing to recreate it.
+ * Transport configuration for connecting to relays.
+ *
+ * Currently only WebSocket, in the future Bluetooth, LocalNetwork, etc.
  */
-export declare const createSharedOwner: (deps: CreateRandomBytesDep & CreateMnemonicDep) => SharedOwner;
+export type OwnerTransport = OwnerWebSocketTransport;
 /**
- * Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner} for read-only
- * data sharing. Extracts the `mnemonic` from the provided {@link SharedOwner},
- * omitting its `writeKey` to ensure read-only access.
+ * WebSocket transport configuration.
+ *
+ * ### Authentication via URL
+ *
+ * The {@link OwnerId} is passed as a URL query parameter. While this approach is
+ * generally discouraged for authentication tokens (they get logged), it's safe
+ * here because OwnerId is pseudonymous and used only for access verification -
+ * it provides no ability to read encrypted data or write changes.
+ *
+ * See: [HTTP headers in Websockets client
+ * API](https://stackoverflow.com/questions/4361173/http-headers-in-websockets-client-api/74564827#74564827)
+ *
+ * ### Error Handling
+ *
+ * When a relay rejects a connection (invalid OwnerId, unauthorized owner, or
+ * server error), the browser WebSocket API does not expose the specific HTTP
+ * status code or reason - it only reports a generic connection failure. The
+ * client automatically retries with exponential backoff and jitter, eventually
+ * succeeding once the configuration or server issue is resolved.
+ *
+ * Legitimate clients will be properly configured with valid credentials, so
+ * automatic retry is OK.
+ *
+ * @see {@link createOwnerWebSocketTransport}
+ * @see {@link parseOwnerIdFromOwnerWebSocketTransportUrl}
  */
-export declare const createSharedReadonlyOwner: (sharedOwner: SharedOwner) => SharedReadonlyOwner;
-/** Creates an {@link Owner} with optional `mnemonic` and `writeKey`. */
-export declare const createOwner: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) => (mnemonic?: string & import("../Types.js").Brand<"Trimmed"> & import("../Types.js").Brand<"MinLength1"> & import("../Types.js").Brand<"Mnemonic">, writeKey?: WriteKey) => Owner;
-export declare const createWriteKey: (deps: CreateRandomBytesDep) => (seed?: MnemonicSeed) => WriteKey;
+export interface OwnerWebSocketTransport {
+    readonly type: "WebSocket";
+    readonly url: string;
+}
 /**
- * An `OwnerRow` represents a row in the `evolu_owner` table, based on an
- * {@link Owner} with an added `timestamp` ({@link TimestampString}) for CRDT
- * sync. It supports all {@link Owner} variants with an optional `writeKey`; use
- * {@link createOwnerRow} to align it with a specific {@link Owner}.
+ * Creates an {@link OwnerWebSocketTransport} for the given relay URL and
+ * {@link OwnerId}.
+ *
+ * The URL must be a WebSocket base URL without query parameters or fragments
+ * (e.g., `wss://relay.evolu.dev`, not `wss://relay.evolu.dev?foo=bar`). The
+ * function appends the `ownerId` as a query parameter.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Create transport "wss://relay.evolu.dev?ownerId=..."
+ * const transport = createOwnerWebSocketTransport({
+ *   url: "wss://relay.evolu.dev",
+ *   ownerId: owner.id,
+ * });
+ *
+ * // Use with createEvolu
+ * const evolu = createEvolu(deps)(Schema, {
+ *   transports: [transport],
+ * });
+ * ```
  */
-export type OwnerRow = Omit<Owner, "writeKey"> & {
-    readonly writeKey: WriteKey | null;
-    readonly timestamp: TimestampString;
-};
+export declare const createOwnerWebSocketTransport: (config: {
+    readonly url: string;
+    readonly ownerId: OwnerId;
+}) => OwnerWebSocketTransport;
 /**
- * Creates an {@link OwnerRow} from any {@link Owner} variant for the
- * `evolu_owner` table, adding a `timestamp` ({@link TimestampString}) for CRDT
- * sync.
+ * Extracts {@link OwnerId} from an {@link OwnerWebSocketTransport} URL query
+ * string.
+ *
+ * Parses the query string `?ownerId=...` and validates that the extracted value
+ * is a valid {@link OwnerId}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * parseOwnerIdFromOwnerWebSocketTransportUrl(
+ *   "/sync?ownerId=_12345678abcdefgh",
+ * );
+ * // Returns: OwnerId or null
+ * ```
  */
-export declare const createOwnerRow: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep & NanoIdLibDep) => (owner: AppOwner | ShardOwner | SharedOwner | SharedReadonlyOwner) => OwnerRow;
+export declare const parseOwnerIdFromOwnerWebSocketTransportUrl: (url: string) => OwnerId | null;
+/** Base interface for all owner errors. */
+export interface BaseOwnerError {
+    readonly ownerId: OwnerId;
+}
 /**
- * Rotates the {@link WriteKey} for an {@link AppOwner}, {@link ShardOwner}, or
- * {@link SharedOwner}, returning a new instance with the updated key.
+ * Usage data for an {@link OwnerId}.
+ *
+ * Tracks storage usage to enforce quotas if needed, and some other stuff.
+ *
+ * TODO:
+ *
+ * - Add transferredBytes for billing and monitoring network usage.
  */
-export declare const rotateWriteKey: <T extends AppOwner | ShardOwner | SharedOwner>(owner: T, newWriteKey: WriteKey) => T;
+export interface OwnerUsage {
+    /** The {@link Owner} this usage data belongs to. */
+    readonly ownerId: OwnerIdBytes;
+    /**
+     * Total logical data bytes stored.
+     *
+     * Measures the size of {@link EncryptedDbChange}s only, excluding
+     * {@link Storage} implementation overhead (with SqliteStorage: indexes,
+     * skiplist columns, etc.). This provides:
+     *
+     * - **Predictable measurement** - same data = same byte count across all
+     *   instances
+     * - **Quota enforcement** - consistent billing/limits independent of storage
+     *   implementation
+     * - **Overhead tracking** - actual Storage size can be compared against this to
+     *   monitor efficiency
+     */
+    readonly storedBytes: NonNegativeInt;
+    /** Tracks the earliest timestamp for timestamp insertion strategies. */
+    readonly firstTimestamp: TimestampBytes | null;
+    /**
+     * Tracks the latest timestamp for timestamp insertion strategies.
+     *
+     * Free relays can use it to identify inactive accounts for cleanup.
+     */
+    readonly lastTimestamp: TimestampBytes | null;
+}
 //# sourceMappingURL=Owner.d.ts.map

package/dist/src/Evolu/Owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Owner.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Owner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Owner.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Owner.ts"],"names":[],"mappings":"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"}