convex-cms 0.0.1

package/dist/component/contentLock.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Content Lock Functions
+ *
+ * Implements optimistic locking for content entries to prevent concurrent edit conflicts.
+ * Provides lock acquisition, release, renewal, and status checking.
+ *
+ * Lock Lifecycle:
+ * 1. User acquires lock when opening content for editing
+ * 2. Lock auto-expires after configured duration (default 30 minutes)
+ * 3. User can renew lock to extend editing session
+ * 4. User releases lock when done editing (or lock auto-expires)
+ * 5. Admins can force-release locks when needed
+ *
+ * Lock Behavior:
+ * - Only one user can hold a lock at a time
+ * - Locks automatically expire to prevent orphaned locks
+ * - The lock holder can update their locked entry
+ * - Other users receive an error when trying to update locked content
+ */
+/**
+ * Query to check the lock status of a content entry.
+ *
+ * Returns detailed information about the current lock state,
+ * including whether it's locked, by whom, and how much time remains.
+ *
+ * @param id - The content entry ID to check
+ * @returns Lock status information
+ *
+ * @example
+ * ```typescript
+ * const status = await ctx.runQuery(api.contentLock.checkLock, {
+ *   id: entryId,
+ * });
+ * if (status.isLocked && status.lockedBy !== currentUserId) {
+ *   console.log(`Entry is locked by ${status.lockedBy}`);
+ * }
+ * ```
+ */
+export declare const checkLock: import("convex/server").RegisteredQuery<"public", {
+    id: import("convex/values").GenericId<"contentEntries">;
+}, Promise<{
+    isLocked: boolean;
+    lockedBy: string | undefined;
+    lockExpiresAt: number | undefined;
+    timeRemaining: number | undefined;
+    isExpired: boolean;
+}>>;
+/**
+ * Query to list all locked content entries.
+ *
+ * Useful for admin dashboards to see which entries are currently
+ * being edited and by whom.
+ *
+ * @param contentTypeId - Optional filter by content type
+ * @param lockedBy - Optional filter by locking user
+ * @param paginationOpts - Pagination options
+ * @returns Paginated list of locked entries
+ */
+export declare const listLockedEntries: import("convex/server").RegisteredQuery<"public", {
+    contentTypeId?: import("convex/values").GenericId<"contentTypes"> | undefined;
+    lockedBy?: string | undefined;
+    paginationOpts: {
+        id?: number;
+        endCursor?: string | null;
+        maximumRowsRead?: number;
+        maximumBytesRead?: number;
+        numItems: number;
+        cursor: string | null;
+    };
+}, Promise<{
+    page: {
+        timeRemaining: number;
+        _id: import("convex/values").GenericId<"contentEntries">;
+        _creationTime: number;
+        deletedAt?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        searchText?: string | undefined;
+        locale?: string | undefined;
+        primaryEntryId?: import("convex/values").GenericId<"contentEntries"> | undefined;
+        scheduledPublishAt?: number | undefined;
+        firstPublishedAt?: number | undefined;
+        lastPublishedAt?: number | undefined;
+        lockedBy?: string | undefined;
+        lockExpiresAt?: number | undefined;
+        contentTypeId: import("convex/values").GenericId<"contentTypes">;
+        slug: string;
+        status: string;
+        data: any;
+        version: number;
+    }[];
+    continueCursor: import("convex/values").GenericId<"contentEntries"> | null;
+    isDone: boolean;
+}>>;
+/**
+ * Mutation to acquire a lock on a content entry.
+ *
+ * Attempts to acquire an exclusive lock on an entry for editing.
+ * The lock will automatically expire after the specified duration.
+ *
+ * Lock acquisition rules:
+ * - If entry is not locked, lock is acquired
+ * - If entry is locked by the same user, lock is renewed
+ * - If entry is locked by another user and lock is expired, lock is acquired
+ * - If entry is locked by another user and lock is active, acquisition fails
+ *
+ * @param id - The content entry ID to lock
+ * @param userId - User ID acquiring the lock
+ * @param lockDuration - Optional lock duration (default 30 min, max 4 hours)
+ * @returns Lock acquisition result with success status and entry
+ *
+ * @example
+ * ```typescript
+ * const result = await ctx.runMutation(api.contentLock.acquireLock, {
+ *   id: entryId,
+ *   userId: currentUserId,
+ *   lockDuration: 60 * 60 * 1000, // 1 hour
+ * });
+ *
+ * if (result.success) {
+ *   console.log("Lock acquired, editing enabled");
+ * } else {
+ *   console.log(`Lock held by ${result.currentLockHolder}`);
+ * }
+ * ```
+ */
+export declare const acquireLock: import("convex/server").RegisteredMutation<"public", {
+    lockDuration?: number | undefined;
+    id: import("convex/values").GenericId<"contentEntries">;
+    userId: string;
+}, Promise<{
+    success: boolean;
+    error: string;
+    currentLockHolder?: undefined;
+    currentLockExpiresAt?: undefined;
+    entry?: undefined;
+} | {
+    success: boolean;
+    error: string;
+    currentLockHolder: string | undefined;
+    currentLockExpiresAt: number | undefined;
+    entry?: undefined;
+} | {
+    success: boolean;
+    entry: {
+        _id: import("convex/values").GenericId<"contentEntries">;
+        _creationTime: number;
+        deletedAt?: number | undefined;
+        createdBy?: string | undefined;
+        updatedBy?: string | undefined;
+        searchText?: string | undefined;
+        locale?: string | undefined;
+        primaryEntryId?: import("convex/values").GenericId<"contentEntries"> | undefined;
+        scheduledPublishAt?: number | undefined;
+        firstPublishedAt?: number | undefined;
+        lastPublishedAt?: number | undefined;
+        lockedBy?: string | undefined;
+        lockExpiresAt?: number | undefined;
+        contentTypeId: import("convex/values").GenericId<"contentTypes">;
+        slug: string;
+        status: string;
+        data: any;
+        version: number;
+    };
+    error?: undefined;
+    currentLockHolder?: undefined;
+    currentLockExpiresAt?: undefined;
+}>>;
+/**
+ * Mutation to release a lock on a content entry.
+ *
+ * Only the lock owner can release their lock. This should be called
+ * when the user finishes editing or navigates away from the editor.
+ *
+ * @param id - The content entry ID to unlock
+ * @param userId - User ID releasing the lock (must match lock owner)
+ * @returns The unlocked content entry
+ *
+ * @throws Error if entry not found
+ * @throws Error if entry not locked by this user
+ *
+ * @example
+ * ```typescript
+ * const entry = await ctx.runMutation(api.contentLock.releaseLock, {
+ *   id: entryId,
+ *   userId: currentUserId,
+ * });
+ * console.log("Lock released");
+ * ```
+ */
+export declare const releaseLock: import("convex/server").RegisteredMutation<"public", {
+    id: import("convex/values").GenericId<"contentEntries">;
+    userId: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"contentEntries">;
+    _creationTime: number;
+    deletedAt?: number | undefined;
+    createdBy?: string | undefined;
+    updatedBy?: string | undefined;
+    searchText?: string | undefined;
+    locale?: string | undefined;
+    primaryEntryId?: import("convex/values").GenericId<"contentEntries"> | undefined;
+    scheduledPublishAt?: number | undefined;
+    firstPublishedAt?: number | undefined;
+    lastPublishedAt?: number | undefined;
+    lockedBy?: string | undefined;
+    lockExpiresAt?: number | undefined;
+    contentTypeId: import("convex/values").GenericId<"contentTypes">;
+    slug: string;
+    status: string;
+    data: any;
+    version: number;
+}>>;
+/**
+ * Mutation to force-release a lock (admin operation).
+ *
+ * Allows administrators to remove locks from entries locked by other users.
+ * This should be used sparingly - only when a user has abandoned an editing
+ * session without releasing their lock, and the auto-expiry hasn't occurred yet.
+ *
+ * @param id - The content entry ID to force unlock
+ * @param releasedBy - User ID performing the force release (for audit trail)
+ * @returns The unlocked content entry
+ *
+ * @throws Error if entry not found
+ * @throws Error if entry is not locked
+ *
+ * @example
+ * ```typescript
+ * // Admin forcing release of abandoned lock
+ * const entry = await ctx.runMutation(api.contentLock.forceReleaseLock, {
+ *   id: entryId,
+ *   releasedBy: adminUserId,
+ * });
+ * console.log("Lock forcibly released");
+ * ```
+ */
+export declare const forceReleaseLock: import("convex/server").RegisteredMutation<"public", {
+    id: import("convex/values").GenericId<"contentEntries">;
+    releasedBy: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"contentEntries">;
+    _creationTime: number;
+    deletedAt?: number | undefined;
+    createdBy?: string | undefined;
+    updatedBy?: string | undefined;
+    searchText?: string | undefined;
+    locale?: string | undefined;
+    primaryEntryId?: import("convex/values").GenericId<"contentEntries"> | undefined;
+    scheduledPublishAt?: number | undefined;
+    firstPublishedAt?: number | undefined;
+    lastPublishedAt?: number | undefined;
+    lockedBy?: string | undefined;
+    lockExpiresAt?: number | undefined;
+    contentTypeId: import("convex/values").GenericId<"contentTypes">;
+    slug: string;
+    status: string;
+    data: any;
+    version: number;
+}>>;
+/**
+ * Mutation to renew an existing lock.
+ *
+ * Extends the lock expiration time for continued editing sessions.
+ * Only the lock owner can renew their lock.
+ *
+ * This is typically called periodically by the client to keep the lock
+ * active during long editing sessions.
+ *
+ * @param id - The content entry ID whose lock to renew
+ * @param userId - User ID renewing the lock (must match lock owner)
+ * @param lockDuration - Optional new lock duration (default 30 min, max 4 hours)
+ * @returns The entry with renewed lock
+ *
+ * @throws Error if entry not found
+ * @throws Error if entry not locked by this user
+ *
+ * @example
+ * ```typescript
+ * // Renew lock every 15 minutes during editing
+ * setInterval(async () => {
+ *   await ctx.runMutation(api.contentLock.renewLock, {
+ *     id: entryId,
+ *     userId: currentUserId,
+ *   });
+ * }, 15 * 60 * 1000);
+ * ```
+ */
+export declare const renewLock: import("convex/server").RegisteredMutation<"public", {
+    lockDuration?: number | undefined;
+    id: import("convex/values").GenericId<"contentEntries">;
+    userId: string;
+}, Promise<{
+    _id: import("convex/values").GenericId<"contentEntries">;
+    _creationTime: number;
+    deletedAt?: number | undefined;
+    createdBy?: string | undefined;
+    updatedBy?: string | undefined;
+    searchText?: string | undefined;
+    locale?: string | undefined;
+    primaryEntryId?: import("convex/values").GenericId<"contentEntries"> | undefined;
+    scheduledPublishAt?: number | undefined;
+    firstPublishedAt?: number | undefined;
+    lastPublishedAt?: number | undefined;
+    lockedBy?: string | undefined;
+    lockExpiresAt?: number | undefined;
+    contentTypeId: import("convex/values").GenericId<"contentTypes">;
+    slug: string;
+    status: string;
+    data: any;
+    version: number;
+}>>;
+/**
+ * Validates that a user can update a locked entry.
+ * This is exported for use by contentEntryMutations.
+ *
+ * @param entry - The content entry to check
+ * @param userId - The user attempting the update
+ * @returns Object with isAllowed boolean and optional error message
+ */
+export declare function validateLockForUpdate(entry: {
+    lockedBy?: string;
+    lockExpiresAt?: number;
+}, userId: string | undefined): {
+    isAllowed: boolean;
+    error?: string;
+};
+//# sourceMappingURL=contentLock.d.ts.map

package/dist/component/contentLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contentLock.d.ts","sourceRoot":"","sources":["../../src/component/contentLock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAmEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,SAAS;;;;;;;;GA4BpB,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2E5B,CAAC;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEtB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;GAgCtB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;GA+B3B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;GA2CpB,CAAC;AAMH;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,KAAK,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EACpD,MAAM,EAAE,MAAM,GAAG,SAAS,GACxB;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAuBxC"}