Conversion logs

Overview

API v2 is the backend for the Publica.la mobile reading apps (Fenice). It powers authentication, library browsing, content download, reader settings, search, and tenant discovery.

- a. General Documentation about ARC

Overview

Overview

This document outlines the process of optimizing audio files, from their initial upload to their final storage in an S3 bucket. The process includes generating random names, optimizing the files, and the ability to customize conversion parameters.

API v2 uses JWT tokens for authentication. Users authenticate via magic link (email code) or social login, and receive a JWT token that must be included in all subsequent requests.

Introduction

Overview

Commerce-related fields surfaced by storefront endpoints, plus the in-app purchase redirect that turns a purchase_link into a completed transaction.

Access Reason Keys

Reference of the cookies a Farfalla tenant stores in a visitor's browser, who owns each, and what category it falls into for GDPR disclosures. Use this doc when a publisher's privacy team asks what to declare or when auditing a privacy notice against actual platform behavior.

Search and recommendation features automatically block crawlers to prevent bots from triggering expensive database queries.

Creates a reader session for the mobile app. Returns content URLs needed to render the publication, varying by format (PDF, EPUB, Audiobook). This replaces the API v1 encrypted-token flow by using JWT authentication directly.

Overview

The commerce domain uses four primary tables: orders, usersplans, payments, and shippingnotes. Each represents a distinct layer of the transaction lifecycle.

A runbook for deleting issues directly from php artisan tinker when the dashboard cannot. The recipes below cover the common scopes (specific IDs, full tenant, taxonomy term, name pattern) and dispatch the file-cleanup job so the bucket does not accumulate orphans.

Introduction

External Auth Embedding - Detailed Technical Procedure

Returns metadata and file URLs needed to download content for offline reading. The response structure varies by content type.

Introduction

Overview

🤌🏼 ¿Qué es?

Introduction

Reference of the SQS queues Farfalla dispatches to, what each queue is for, and how queue names are derived per environment. Use this doc when wiring a new job, debugging a stuck pipeline in Horizon, or reading the SQS console.

The features system controls tenant access to platform capabilities, supporting both boolean flags (on/off) and numeric limits (quotas). Features are granted at the plan level, may be overridden per-tenant, and a separate set of platform-level kill switches can disable them globally.

When a tenant saves payment settings in the control panel, the platform makes a live API call to the gateway to verify the credentials work. This is not format validation; it is a real request to the gateway using the credentials the tenant just entered. If the call fails, the save is rejected.

The gateway_type column on Orders identifies the payment gateway or assignment source. Not all values represent real payment processors; several represent administrative or institutional assignment paths that never touch a payment gateway.

The checkout does not let the user choose which gateway to use. The platform selects it automatically from the tenant's configured gateways, picking the first one (in priority order) whose supported currencies include the cart's currency.

Terms used across the commerce domain that are either non-obvious, have names that conflict with their meaning, or are used inconsistently across the codebase.

This document describes how Farfalla exposes operational health checks and how OhDear monitors them for automated alerting.

Endpoints for in-app help and feedback. Both endpoints use multi-tenant mode (do NOT send X-Farfalla-Tenant-Id).

Adding a currency touches two surfaces; both must be updated, or the currency appears in plan-creation UIs but no gateway is ever offered for it at checkout. Use this guide when onboarding a new currency end-to-end.

This document describes how to integrate Delfino into Host applications (Farfalla/Fenice) and Client applications (Volpe).

AI-powered reader features: translate, text-to-speech, dictionary, and text analysis (explain/expand/summarize). All endpoints require the reader-token header.

AI-powered reader features: translate, text-to-speech, dictionary, and text analysis (explain/expand/summarize). All endpoints use single-tenant mode (require X-Farfalla-Tenant-Id) and require the reader-token header.

The InventoryService is responsible for managing the available publication listings, implementing filtering logic, and providing search capabilities across the content catalog.

What is it?

Each payment gateway sends webhook notifications to Farfalla when payment state changes. All gateways share a single IPN controller, exposed at two routes:

Searches for text within the current issue using SingleStore full-text search. Returns highlighted snippets with location information for navigating to matches. Requires the reader-token header.

Introduction

Endpoints for browsing the content library within a specific tenant. All library endpoints use single-tenant mode and require the X-Farfalla-Tenant-Id header.

This integration allow make an automatic auth to specific user when this is try to login from an configuration LTI.

These order types have one thing in common: none of them go through a payment gateway at checkout time. No gateway call is made, and access is granted immediately.

Overview

Description

Endpoints for managing user highlights and annotations within the reader. All endpoints require the reader-token header.

Endpoints for managing user highlights and annotations within the reader. All endpoints use single-tenant mode (require X-Farfalla-Tenant-Id) and require the reader-token header.

Delfino is a TypeScript RPC bridge library that enables type-safe bidirectional communication between Volpe (an iframe-based reader) and its host applications (Farfalla and Fenice). The library encapsulates all Comlink complexity, providing simple, typed APIs for both sides of the communication.

Our tenant supports multiple authentication methods to integrate external applications. Each integration method can be used according to specific scenarios and requirements.

Repository: gitlab.com/publicala/farfalla

The payments table works like a bank ledger: every financial event is a new row. Financial fields are never mutated after insert. This is not an accident; it is the core invariant that makes balance calculation correct.

A set of scheduled jobs keep gateway transaction state aligned with Farfalla's orders and payments tables. They cover gateway-initiated changes that did not reach the platform through an Instant Payment Notification (see IPNs): status updates, gateway keys, and missing payment rows.

Entry point into the payments domain: the four active gateways (MercadoPago, Stripe, Yuno, PayU), coupons, manual payments, and the standard checkout flow.

Platform features are global kill switches that override tenant-level feature access. Use them when a capability must be turned off across the entire platform during an emergency (high database load, payment provider issues, or processing backlogs).

Polpo is the internal API used by the Volpe reader. It handles reader session initialization, user notes/highlights, in-reader search, and AI-powered integrations (translate, listen, dictionary, explain/expand/summarize).

Endpoints for reader sessions, configuration, reading position persistence, text search, and content download. All endpoints use single-tenant mode and require the X-Farfalla-Tenant-Id header.

Get Reader Settings

A refund can arrive through three conceptual paths. Each path ends by inserting a new row in payments with status = 'refunded'; the original approved row is never modified. See Payment Ledger Model.

Overview

Integration Route

Saves the user's reading position. The payload structure varies by content type.

Full-text search within the content of a publication.

Endpoints for searching content within a single tenant or across all tenants the user belongs to.

Introduction

Reader session management. The POST /sessions endpoint is the entry point for the reader — it initializes the session and returns all the content URLs needed to render the publication.

This page describes the ShippingCarrier model, its two categorization dimensions, the shippingbyprovince feature, dashboard settings, and how checkout resolves which carriers to offer the user. SN integration is covered from the overview and the sibling topic docs.

A Shipping Note (SN) is the internal record that materializes a physical shipment within Farfalla. Each SN represents a concrete delivery cycle: the tenant operator sees it in the dashboard, ships the package through their courier of choice, and manually updates the status as it progresses.

This page describes the tables, columns, and relationships that underpin the Shipping Notes subdomain. The terminology and conceptual model live in the overview; it assumes the reader already knows what an SN is and how it relates to order, UP, and payment.

This page describes how each Shipping Note is born and how dispatch cycles are completed. It covers everything from the cart mounting the shipping payment to the recurring creation of SNs in annual subscriptions, including idempotency guarantees and flow edge cases.

This page describes how the tenant logistics operator works with already-created SNs: dashboard, transitions, notifications, refunds, cancellations, and the two Nova actions reserved for super admins. Statuses and creation mechanics live in Data model and Generation.

When a user buys a physical product, the checkout records two separate entries in the payments table: one for the product, one for the carrier cost. The carrier cost entry has no associated UserPlan.

Overview

The StorefrontService is responsible for building and organizing shelves in the publication storefront. It acts as the main abstraction layer between controllers and the underlying inventory layer.

This document covers the MercadoPago-specific subscription checkout flow. For the IPN lifecycle and refund handling, see IPNs and Refund Flow.

This document describes how Farfalla uses Laravel Telescope for debugging and monitoring across all environments, including cross-subdomain request tracking.

The tenant resolver decides which tenant a request belongs to and configures the application accordingly, with a cache-first design that keeps tenant lookups off the database on every request. This doc explains the resolution path, the two-tier cache, and the invariants that keep cache and database consistent.

Overview

Endpoints for listing tenants (stores) the authenticated user could sign up for.

This integration allow make an automatic auth to specific user when this is from an URL added in configurations for these user.

Endpoints for user profile, continue reading, and push notification management.

Introduction

Yuno has two checkout flows that behave differently with respect to order creation:

Summary

Yuno is a payment orchestrator that allows Farfalla to offer multiple payment methods (cards, local wallets, bank transfers, etc.) through a single integration. In Farfalla it is integrated as one more gateway, behind the feature flag yunocheckoutenabled.

Summary

Summary

Summary

Summary