Skip to main content

​
addVerseToCollection

Add a Bible verse to an existing collection.
​
verseId
string
required
The unique identifier of the Bible verse
​
collectionId
Id<'collections'>
required
The unique identifier of the collection to add the verse to
​
userId
string
required
The user ID requesting the operation to verify collection ownership
​
verseText
string
required
The text content of the verse
​
chapterId
string
required
The unique identifier of the chapter containing this verse
​
bibleId
string
required
The Bible translation identifier (e.g., “KJV”, “NIV”)
​
verseCollectionId
Id<'collectionVerses'>
The unique identifier of the newly created collection verse entry
This function validates that the requesting user owns the collection before allowing the verse to be added.
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

function AddVerseButton({
  verseId,
  verseText,
  chapterId,
  bibleId,
  collectionId
}: {
  verseId: string;
  verseText: string;
  chapterId: string;
  bibleId: string;
  collectionId: Id<"collections">;
}) {
  const addVerse = useMutation(api.verseCollections.addVerseToCollection);

  const handleAdd = async () => {
    await addVerse({
      verseId,
      verseText,
      chapterId,
      bibleId,
      collectionId,
      userId: "user_123"
    });
  };

  return <button onClick={handleAdd}>Add to Collection</button>;
}

​
getVerseCollections

Retrieve all verses in a specific collection.
​
collectionId
Id<'collections'>
required
The unique identifier of the collection
​
userId
string
required
The user ID requesting access to verify collection ownership
​
verses
array
Array of verse objects in the collection
This function validates that the requesting user owns the collection before returning verses.
import { useQuery } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

function CollectionVerses({ 
  collectionId 
}: { 
  collectionId: Id<"collections"> 
}) {
  const verses = useQuery(api.verseCollections.getVerseCollections, {
    collectionId,
    userId: "user_123"
  });

  if (!verses) return <div>Loading...</div>;

  return (
    <div>
      <h3>Verses in Collection</h3>
      {verses.map((verse) => (
        <div key={verse._id}>
          <p>{verse.verseText}</p>
          <small>From {verse.chapterId} ({verse.bibleId})</small>
        </div>
      ))}
    </div>
  );
}

​
deleteVerseFromCollection

Remove a verse from a collection.
​
verseCollectionId
Id<'collectionVerses'>
required
The unique identifier of the collection verse entry to delete
​
collectionId
Id<'collections'>
required
The unique identifier of the collection (used for access validation)
​
userId
string
required
The user ID requesting the deletion to verify collection ownership
​
response
null
Returns null on successful deletion
This function validates that the requesting user owns the collection before allowing the verse to be removed. This only removes the verse from the collection, not from the Bible database.
import { useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";
import { Id } from "@/convex/_generated/dataModel";

function RemoveVerseButton({
  verseCollectionId,
  collectionId
}: {
  verseCollectionId: Id<"collectionVerses">;
  collectionId: Id<"collections">;
}) {
  const removeVerse = useMutation(api.verseCollections.deleteVerseFromCollection);

  const handleRemove = async () => {
    if (confirm("Remove this verse from the collection?")) {
      await removeVerse({
        verseCollectionId,
        collectionId,
        userId: "user_123"
      });
    }
  };

  return <button onClick={handleRemove}>Remove</button>;
}
The verseCollectionId parameter refers to the _id of the entry in the collectionVerses table, not the verseId field. Make sure to pass the correct identifier when removing verses.