My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(*
2 * Copyright (c) 2014, OCaml.org project
3 * Copyright (c) 2015 KC Sivaramakrishnan <sk826@cl.cam.ac.uk>
4 *
5 * Permission to use, copy, modify, and distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
8 *
9 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 *)
17
18(** River RSS/Atom feed aggregator *)
19
20(** {1 Session Management} *)
21
22type session
23(** An abstract River session for fetching feeds.
24
25 The session manages HTTP connections and is tied to an Eio switch
26 for proper resource cleanup. *)
27
28val init :
29 sw:Eio.Switch.t ->
30 < clock : float Eio.Time.clock_ty Eio.Resource.t;
31 fs : Eio.Fs.dir_ty Eio.Path.t;
32 net : [ `Generic | `Unix ] Eio.Net.ty Eio.Resource.t; .. > ->
33 session
34(** [init ~sw env] creates a new River session.
35
36 The session is configured with appropriate defaults for fetching feeds:
37 - User-Agent: "OCaml-River/1.0"
38 - Automatic redirect following (max 5 redirects)
39 - TLS verification enabled
40
41 @param sw The switch for resource management
42 @param env The Eio environment *)
43
44val with_session :
45 < clock : float Eio.Time.clock_ty Eio.Resource.t;
46 fs : Eio.Fs.dir_ty Eio.Path.t;
47 net : [ `Generic | `Unix ] Eio.Net.ty Eio.Resource.t; .. > ->
48 (session -> 'a) -> 'a
49(** [with_session env f] creates a session and automatically manages its lifecycle.
50
51 This is the recommended way to use River as it ensures proper cleanup.
52
53 @param env The Eio environment
54 @param f The function to run with the session *)
55
56(** {1 Feed Sources and Fetching} *)
57
58type source = { name : string; url : string }
59(** The source of a feed. *)
60
61type feed
62(** An Atom, RSS2, or JSON Feed. *)
63
64type post
65(** A post from a feed. *)
66
67val fetch : session -> source -> feed
68(** [fetch session source] returns an Atom or RSS feed from a source.
69
70 @param session The River session
71 @param source The feed source to fetch *)
72
73val name : feed -> string
74(** [name feed] is the name of the feed source passed to [fetch]. *)
75
76val url : feed -> string
77(** [url feed] is the url of the feed source passed to [fetch]. *)
78
79val posts : feed list -> post list
80(** [posts feeds] is the list of deduplicated posts of the given feeds. *)
81
82val feed : post -> feed
83(** [feed post] is the feed the post originates from. *)
84
85val title : post -> string
86(** [title post] is the title of the post. *)
87
88val link : post -> Uri.t option
89(** [link post] is the link of the post. *)
90
91val date : post -> Syndic.Date.t option
92(** [date post] is the date of the post. *)
93
94val author : post -> string
95(** [author post] is the author of the post. *)
96
97val email : post -> string
98(** [email post] is the email of the post. *)
99
100val content : post -> string
101(** [content post] is the content of the post. *)
102
103val id : post -> string
104(** [id post] is the unique identifier of the post. *)
105
106val tags : post -> string list
107(** [tags post] is the list of tags associated with the post. *)
108
109val summary : post -> string option
110(** [summary post] is the summary/excerpt of the post, if available. *)
111
112val meta_description : post -> string option
113(** [meta_description post] is the meta description of the post on the origin
114 site.
115
116 To get the meta description, we make get the content of [link post] and look
117 for an HTML meta tag with the name "description" or "og:description".*)
118
119val seo_image : post -> string option
120(** [seo_image post] is the image to be used by social networks and links to the
121 post.
122
123 To get the seo image, we make get the content of [link post] and look for an
124 HTML meta tag with the name "og:image" or "twitter:image". *)
125
126val create_atom_entries : post list -> Syndic.Atom.entry list
127(** [create_atom_feed posts] creates a list of atom entries, which can then be
128 used to create an atom feed that is an aggregate of the posts. *)
129
130(** {1 JSON Feed Support} *)
131
132val create_jsonfeed_items : post list -> Jsonfeed.Item.t list
133(** [create_jsonfeed_items posts] creates a list of JSONFeed items from posts. *)
134
135val create_jsonfeed :
136 title:string ->
137 ?home_page_url:string ->
138 ?feed_url:string ->
139 ?description:string ->
140 ?icon:string ->
141 ?favicon:string ->
142 post list ->
143 Jsonfeed.t
144(** [create_jsonfeed ~title ?home_page_url ?feed_url ?description posts]
145 creates a complete JSONFeed from the given posts.
146
147 @param title The feed title (required)
148 @param home_page_url The URL of the website the feed represents
149 @param feed_url The URL of the feed itself
150 @param description A description of the feed
151 @param icon URL of an icon for the feed (512x512 recommended)
152 @param favicon URL of a favicon for the feed (64x64 recommended)
153 @param posts The posts to include in the feed *)
154
155val jsonfeed_to_string : ?minify:bool -> Jsonfeed.t -> (string, string) result
156(** [jsonfeed_to_string ?minify jsonfeed] serializes a JSONFeed to a string.
157
158 @param minify If true, output compact JSON; if false, pretty-print (default: false) *)
159
160type feed_content = Atom of Syndic.Atom.feed | Rss2 of Syndic.Rss2.channel | JSONFeed of Jsonfeed.t
161(** The native format of a feed. *)
162
163val feed_content : feed -> feed_content
164(** [feed_content feed] returns the feed in its native format (Atom, RSS2, or JSONFeed).
165 This allows access to format-specific features like JSONFeed attachments. *)