Skip to content

ports_primary

Define how services can be used by external consumers (e.g., HTTP API, CLI).

AuthServicePort

Primary port for authentication operations.

login_with_google abstractmethod 

login_with_google(id_token: str) -> str

Authenticate via Google and return a JWT access token.

Verifies the Google ID token, finds or creates the user, and returns a signed JWT.

RecipeExportServicePort

export_recipes_to_markdown abstractmethod 

export_recipes_to_markdown(user_id: UUID) -> bytes

Export the user's recipes as a ZIP archive containing Markdown and images.

export_recipes_to_word abstractmethod 

export_recipes_to_word(user_id: UUID) -> bytes

Export the user's recipes as Word document.

RecipeImportServicePort

Primary port for importing recipes from external sources.

parse_instagram abstractmethod 

parse_instagram(data: InstagramResponse) -> list[ParsedRecipe]

Parse Instagram data and return parsed recipes with image URLs.

RecipeServicePort

add_recipe_image abstractmethod 

add_recipe_image(recipe_id: UUID, user_id: UUID, content: bytes, filename: str) -> UUID

Add an image to a recipe owned by user_id and return its image ID.

create_recipe abstractmethod 

create_recipe(data: RecipeCreate, owner_id: UUID) -> RecipeEntity

Persist a new recipe with all related entities and return the created Recipe.

create_recipes abstractmethod 

create_recipes(data: list[RecipeCreate], owner_id: UUID) -> list[RecipeEntity]

Persist multiple recipes atomically and return all created Recipe entities.

delete_recipe abstractmethod 

delete_recipe(recipe_id: UUID, user_id: UUID) -> bool

Delete a recipe by ID. Returns True if deleted, False if not found/owned.

delete_recipe_image abstractmethod 

delete_recipe_image(image_id: UUID, user_id: UUID) -> bool

Delete an image from storage and database. Returns True if deleted, False if not found/owned.

get_recipe_by_id abstractmethod 

get_recipe_by_id(recipe_id: UUID, user_id: UUID) -> RecipeEntity | None

Retrieve a recipe by its ID, scoped to the given user.

get_recipe_image abstractmethod 

get_recipe_image(image_id: UUID, user_id: UUID) -> ImageResponse | None

Retrieve image bytes for a given image ID, scoped to the given user.

search_recipes abstractmethod 

search_recipes(
    user_id: UUID,
    recipe_id: UUID | None = None,
    title: str | None = None,
    category: str | None = None,
    is_veggie: bool | None = None,
    season: str | None = None,
    limit: int | None = None,
    offset: int = 0,
    ownership: str | None = None,
) -> PaginatedResult

Search for recipes using dynamic filters, visible to the given user.

update_recipe abstractmethod 

update_recipe(
    recipe_id: UUID, data: RecipeUpdate, user_id: UUID
) -> RecipeEntity | None

Full replacement of a recipe (PUT semantics). Returns None if not found/owned.

RecipeShareServicePort

Primary port for recipe sharing operations.

accept_all_shares abstractmethod 

accept_all_shares(user_id: UUID) -> list[RecipeShareEntity]

Accept all pending share invitations for the current user.

accept_share abstractmethod 

accept_share(share_id: UUID, user_id: UUID) -> RecipeShareEntity

Accept a share invitation.

get_pending_shares abstractmethod 

get_pending_shares(user_id: UUID) -> list[RecipeShareEntity]

List pending share invitations for the current user.

get_pending_shares_count abstractmethod 

get_pending_shares_count(user_id: UUID) -> int

Count pending share invitations for the current user.

get_recipe_shares abstractmethod 

get_recipe_shares(recipe_id: UUID, user_id: UUID) -> list[RecipeShareEntity]

List all collaborators for a recipe. Only the owner can view this.

leave_recipe abstractmethod 

leave_recipe(recipe_id: UUID, user_id: UUID) -> bool

Remove yourself from a shared recipe.

reject_share abstractmethod 

reject_share(share_id: UUID, user_id: UUID) -> RecipeShareEntity

Reject a share invitation.

remove_share abstractmethod 

remove_share(share_id: UUID, user_id: UUID) -> bool

Remove a share (owner revokes or shared user leaves).

share_recipe abstractmethod 

share_recipe(
    recipe_id: UUID, email: str, role: ShareRole, user_id: UUID
) -> RecipeShareEntity

Share a recipe with another user by email. Only the owner can share.