Skip to main content

​
updateCard

Updates basic card fields (content, url, tags, notes). Automatically triggers AI reprocessing when content changes. 
import { useMutation } from "convex/react";
import { api } from "@teak/convex";

function EditCardForm({ cardId }: { cardId: Id<"cards"> }) {
  const updateCard = useMutation(api.card.updateCard.updateCard);

  const handleSave = async (content: string) => {
    await updateCard({
      id: cardId,
      content,
      tags: ["updated", "important"]
    });
  };

  return <form onSubmit={handleSave}>{/* ... */}</form>;
}

​
Arguments

​
id
Id<'cards'>
required
The unique identifier of the card to update.
​
content
string
Updated card content. For quote cards, quotation marks are automatically normalized.Triggers AI reprocessing: When content changes, the card re-enters the processing pipeline for metadata extraction and categorization.
​
url
string
Updated URL. Typically used for link cards.
​
tags
string[]
Updated tags array. Replaces existing tags completely.
tags: ["work", "important"] // Replaces all previous tags
​
notes
string
Updated notes text. Replaces existing notes.

​
Returns

​
result
null
Returns null on success. Throws an error if the operation fails.

​
Behavior

Verifies:
  1. User is authenticated
  2. Card exists
  3. Card belongs to the authenticated user
Throws an error if any check fails.
For quote-type cards, content is automatically normalized:
// Input
content: '"Updated quote text" - Author'

// Stored as
content: 'Updated quote text - Author'
Quotation marks are removed and content is cleaned.
When content is updated:
  1. Sets processingStatus.metadata to "pending"
  2. For link cards, also sets processingStatus.categorize to "pending"
  3. Schedules cardProcessingWorkflow to run asynchronously
  4. Workflow re-extracts AI metadata, tags, and summaries
This ensures cards stay up-to-date with the latest AI models.
Always updates updatedAt to current timestamp, regardless of which field changed.

​
Error Handling

​
User must be authenticated
Error
Thrown when no authenticated session exists.
​
Card not found
Error
Thrown when card with given ID doesn’t exist.
​
Not authorized to update this card
Error
Thrown when authenticated user doesn’t own the card.

​
updateCardField

Unified mutation for updating any card field or performing card operations (favorite, delete, restore). 
import { useMutation } from "convex/react";
import { api } from "@teak/convex";

const updateCardField = useMutation(api.card.updateCard.updateCardField);

// Toggle favorite status
await updateCardField({
  cardId,
  field: "isFavorited"
});

​
Arguments

​
cardId
Id<'cards'>
required
The unique identifier of the card to update.
​
field
string
required
The field or operation to perform:
  • "content" - Update main content
  • "url" - Update URL
  • "notes" - Update notes
  • "tags" - Update user tags
  • "aiSummary" - Update AI summary
  • "isFavorited" - Toggle favorite status
  • "removeAiTag" - Remove specific AI tag
  • "delete" - Soft delete card
  • "restore" - Restore deleted card
​
value
any
The new value for the field. Type depends on the field:
  • content, url, notes, aiSummary: string
  • tags: string[]
  • isFavorited, delete, restore: not needed (operation-based)
​
tagToRemove
string
Required when field is "removeAiTag". Specifies which AI tag to remove.

​
Returns

​
result
any
Returns the update result (typically the card object or null). Return type varies based on operation.

​
Field-Specific Behavior

Updates card content:
  • Trims whitespace
  • Normalizes quotes for quote-type cards
  • Sets processingStatus.metadata to pending if content changed
  • For link cards, also sets processingStatus.categorize to pending
  • Triggers cardProcessingWorkflow asynchronously
Updates card URL:
  • Trims whitespace, sets to undefined if empty
  • Sets processingStatus.classify to pending
  • Sets processingStatus.metadata to pending
  • Sets processingStatus.categorize to pending
  • Clears existing linkPreview and linkCategory metadata
  • Sets metadataStatus to "pending"
  • Triggers complete reprocessing pipeline
Updates notes field:
  • Trims whitespace, sets to undefined if empty
  • Does not trigger AI reprocessing
Replaces user-defined tags:
  • Accepts array of strings
  • Sets to undefined if empty array
  • Does not trigger AI reprocessing
Manually updates AI-generated summary:
  • Trims whitespace, sets to undefined if empty
  • Does not trigger automatic regeneration
Toggles favorite status:
  • Flips boolean value: true → false, false → true, undefined → true
  • No value parameter needed
Removes a specific AI-generated tag:
  • Requires tagToRemove parameter
  • Filters out the specified tag
  • Sets aiTags to undefined if no tags remain
  • Returns card unchanged if tag not found or no AI tags exist
Soft deletes the card:
  • Sets isDeleted to true
  • Sets deletedAt to current timestamp
  • Card remains in database but hidden from normal queries
  • Can be restored with "restore" operation
Restores a soft-deleted card:
  • Sets isDeleted to undefined
  • Sets deletedAt to undefined
  • Throws error if card is not deleted
  • Card reappears in normal queries

​
Error Handling

​
User must be authenticated
Error
Thrown when no authenticated session exists.
​
Card not found
Error
Thrown when card with given ID doesn’t exist.
​
Not authorized to modify this card
Error
Thrown when authenticated user doesn’t own the card.
​
Card is not deleted
Error
Thrown when attempting to restore a card that isn’t deleted.
​
Unsupported field: [field]
Error
Thrown when an invalid field name is provided.

​
Source References

  • updateCard: packages/convex/card/updateCard.ts:12
  • updateCardField: packages/convex/card/updateCard.ts:86

Build docs developers (and LLMs) love

Get started for freeTalk to us