fopost 0.1.0 → 0.3.0

data/lib/fopost/resources/analytics.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module Fopost
+  module Resources
+    # `client.analytics` — deeper posting analytics.
+    #
+    # Derived from the repeated readings the platform collector takes of every
+    # post as it ages. Every call needs the `analytics` scope.
+    class Analytics < Base
+      # How engagement accumulates with a post's age, and where the half-life
+      # falls. `days` selects posts by publish time, not reading time.
+      def decay(days: nil, workspace_id: nil, account_id: nil)
+        query = compact_nil('days' => days, 'workspace_id' => workspace_id, 'accountId' => account_id)
+        ContentDecay.new(unwrap(http.get('/analytics/decay', query)))
+      end
+
+      # Weekly posting cadence set against what each cadence earned per post.
+      def frequency(days: nil, workspace_id: nil, account_id: nil)
+        query = compact_nil('days' => days, 'workspace_id' => workspace_id, 'accountId' => account_id)
+        PostingFrequency.new(unwrap(http.get('/analytics/frequency', query)))
+      end
+
+      # Every reading held for one post, oldest first, one timeline per
+      # delivery. `id_or_permalink` is a FoPost post id or the permalink of a
+      # post made natively on the network.
+      def timeline(id_or_permalink)
+        path = "/analytics/posts/#{CGI.escape(id_or_permalink.to_s)}/timeline"
+        PostTimeline.new(unwrap(http.get(path)))
+      end
+
+      # Readings recorded after `since`, oldest first, with a cursor to
+      # continue. Poll this to mirror the metrics into your own store; omitting
+      # `since` gives the last seven days.
+      def changes(since: nil, limit: nil, workspace_id: nil, account_id: nil)
+        query = compact_nil(
+          'since' => iso8601(since),
+          'limit' => limit,
+          'workspace_id' => workspace_id,
+          'accountId' => account_id
+        )
+        MetricChangePage.new(unwrap(http.get('/analytics/changes', query)))
+      end
+
+      # Re-read one post from the network now. Spends the same per-user budget
+      # as a full collection run, so a burst answers 429 with `retryAfter`.
+      def collect_post(id_or_permalink)
+        path = "/posts/#{CGI.escape(id_or_permalink.to_s)}/analytics/collect"
+        CollectPostResult.new(unwrap(http.post(path)))
+      end
+
+      # Posts on the account that never went out through FoPost, newest first.
+      def native_posts(account_id, page: 1, per_page: 20, days: nil)
+        query = compact_nil('page' => page, 'per_page' => per_page, 'days' => days)
+        body = http.get("/accounts/#{account_id}/native-posts", query)
+        items = parse_list(NativePost, body.is_a?(Hash) ? body['data'] : body)
+        raw_meta = body.is_a?(Hash) ? body['meta'] : nil
+        Page.new(items: items, meta: InboxPageMeta.new(raw_meta.is_a?(Hash) ? raw_meta : {}))
+      end
+    end
+  end
+end

data/lib/fopost/resources/blog.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.blog` — articles written for a website, as opposed to posts
+    # that go to a social network.
+    #
+    # Reads, settings and keyword edits need the `posts` scope. Anything that
+    # spends credits ({#suggest_seeds}, {#plan_keywords}, {#request_article},
+    # {#regenerate_article}) needs `ai` and answers 402 on an empty balance;
+    # {#publish_article} needs `publish` and answers 409 `no_target` when the
+    # settings name nowhere to publish.
+    class Blog < Base
+      # ── Settings ──────────────────────────────────────────────────
+
+      def get_settings(workspace_id)
+        BlogSettings.new(unwrap(http.get('/blog/settings', { 'workspace_id' => workspace_id })))
+      end
+
+      # Partial update: only what you pass is sent.
+      #
+      # The answer carries `website_secret` only on the update that first sets
+      # `website_url`; keep it, it is never shown again. Pass `nil` to clear a
+      # nullable field.
+      def update_settings(workspace_id, site_url: UNSET, topic: UNSET, audience: UNSET, goal: UNSET,
+                          focus_topics: UNSET, avoid_topics: UNSET, language: UNSET, location_code: UNSET,
+                          cadence_per_week: UNSET, review_hold_days: UNSET, image_tier: UNSET,
+                          in_body_images: UNSET, min_words: UNSET, max_words: UNSET, brand_voice_id: UNSET,
+                          target_kind: UNSET, target_account_id: UNSET, website_url: UNSET)
+        body = compact_unset(
+          'siteUrl' => site_url,
+          'topic' => topic,
+          'audience' => audience,
+          'goal' => goal,
+          'focusTopics' => focus_topics,
+          'avoidTopics' => avoid_topics,
+          'language' => language,
+          'locationCode' => location_code,
+          'cadencePerWeek' => cadence_per_week,
+          'reviewHoldDays' => review_hold_days,
+          'imageTier' => image_tier,
+          'inBodyImages' => in_body_images,
+          'minWords' => min_words,
+          'maxWords' => max_words,
+          'brandVoiceId' => brand_voice_id,
+          'targetKind' => target_kind,
+          'targetAccountId' => target_account_id,
+          'websiteUrl' => website_url
+        )
+        response = as_hash(unwrap(http.patch('/blog/settings', { 'workspaceId' => workspace_id }.merge(body))))
+        BlogSettingsUpdate.new('settings' => response, 'website_secret' => response['website_secret'])
+      end
+
+      # Issue a new website secret; the old one stops verifying at once.
+      # Returns the secret, shown this once.
+      def rotate_website_secret(workspace_id)
+        result = as_hash(unwrap(http.post('/blog/settings/website-secret', { 'workspaceId' => workspace_id })))
+        result['website_secret'].to_s
+      end
+
+      # Send a signed `article.test` delivery to `website_url`. A site that
+      # does not answer 2xx comes back as a 502 `Fopost::Error` whose body
+      # carries the site's `http_status`.
+      def test_website(workspace_id)
+        BlogWebsiteTest.new(unwrap(http.post('/blog/settings/website-test', { 'workspaceId' => workspace_id })))
+      end
+
+      # ── Keywords ──────────────────────────────────────────────────
+
+      # `status` takes one status or an array of them.
+      def list_keywords(workspace_id, status: nil, limit: nil)
+        params = { 'workspace_id' => workspace_id, 'status' => csv(status), 'limit' => limit }
+        parse_list(BlogKeyword, unwrap(http.get('/blog/keywords', params)))
+      end
+
+      # About 10 search terms from the blog goal and topics, to edit before
+      # {#plan_keywords}. Pass the current `seeds` to refine them and `prompt`
+      # (up to 500 characters) to steer. Needs `ai`.
+      def suggest_seeds(workspace_id, seeds: nil, prompt: nil)
+        body = compact_nil('workspaceId' => workspace_id, 'seeds' => seeds, 'prompt' => prompt)
+        as_hash(unwrap(http.post('/blog/keywords/suggest', body)))['seeds'] || []
+      end
+
+      # Queue a research run; it answers before the run finishes. Results land
+      # as `suggested` keywords and never fill the calendar; set one to
+      # `planned` with {#update_keyword} to pick it. Follow the run in
+      # `plan_run` on {#get_settings}. Needs `ai`.
+      def plan_keywords(workspace_id, seeds: nil)
+        body = compact_nil('workspaceId' => workspace_id, 'seeds' => seeds)
+        as_hash(unwrap(http.post('/blog/keywords/plan', body)))
+      end
+
+      # `planned_for` is a date, YYYY-MM-DD.
+      def add_keyword(workspace_id, keyword:, planned_for: nil)
+        body = compact_nil('workspaceId' => workspace_id, 'keyword' => keyword, 'plannedFor' => date(planned_for))
+        BlogKeyword.new(unwrap(http.post('/blog/keywords', body)))
+      end
+
+      # Partial update. `status: 'planned'` picks the keyword and gives it the
+      # next free date; `planned_for: nil` takes it off the calendar.
+      def update_keyword(workspace_id, keyword_id, status: UNSET, planned_for: UNSET)
+        body = compact_unset('status' => status, 'plannedFor' => UNSET.equal?(planned_for) ? UNSET : date(planned_for))
+        BlogKeyword.new(unwrap(patch("/blog/keywords/#{keyword_id}", workspace_id, body)))
+      end
+
+      def delete_keyword(workspace_id, keyword_id)
+        http.request(:delete, "/blog/keywords/#{keyword_id}", params: workspace(workspace_id))
+        nil
+      end
+
+      # ── Articles ──────────────────────────────────────────────────
+
+      # `status` takes one status or an array of them.
+      def list_articles(workspace_id, status: nil, limit: nil)
+        params = { 'workspace_id' => workspace_id, 'status' => csv(status), 'limit' => limit }
+        parse_list(BlogArticle, unwrap(http.get('/blog/articles', params)))
+      end
+
+      # Queue an article. Give one of `title`, `keyword` or `keyword_id` (a
+      # keyword from the plan). The article comes back `queued`; poll
+      # {#get_article} or wait for the `article.published` webhook. Needs `ai`.
+      def request_article(workspace_id, title: nil, keyword: nil, keyword_id: nil, instructions: nil)
+        body = compact_nil(
+          'workspaceId' => workspace_id,
+          'title' => title,
+          'keyword' => keyword,
+          'keywordId' => keyword_id,
+          'instructions' => instructions
+        )
+        BlogArticle.new(unwrap(http.post('/blog/articles', body)))
+      end
+
+      def get_article(workspace_id, article_id)
+        BlogArticleFull.new(unwrap(http.get("/blog/articles/#{article_id}", workspace(workspace_id))))
+      end
+
+      # Partial update. An article still being written or already publishing
+      # answers 409. `publish_at` puts an article in review on the calendar (a
+      # draft answers 409 until submitted with {#submit_article});
+      # `publish_at: nil` returns it to draft.
+      def update_article(workspace_id, article_id, title: UNSET, slug: UNSET, excerpt: UNSET, meta_title: UNSET,
+                         meta_description: UNSET, body_markdown: UNSET, tags: UNSET, publish_at: UNSET)
+        body = compact_unset(
+          'title' => title,
+          'slug' => slug,
+          'excerpt' => excerpt,
+          'metaTitle' => meta_title,
+          'metaDescription' => meta_description,
+          'bodyMarkdown' => body_markdown,
+          'tags' => tags,
+          'publishAt' => UNSET.equal?(publish_at) ? UNSET : iso8601(publish_at)
+        )
+        BlogArticleFull.new(unwrap(patch("/blog/articles/#{article_id}", workspace_id, body)))
+      end
+
+      # Write it again from the same brief. Needs `ai`.
+      def regenerate_article(workspace_id, article_id)
+        BlogArticle.new(unwrap(http.request(:post, "/blog/articles/#{article_id}/regenerate",
+                                            params: workspace(workspace_id))))
+      end
+
+      # Publish an article in review to the configured target. Needs
+      # `publish`; a draft answers 409 until submitted with {#submit_article},
+      # and 409 `no_target` means the settings name nowhere to publish.
+      def publish_article(workspace_id, article_id)
+        BlogArticle.new(unwrap(http.request(:post, "/blog/articles/#{article_id}/publish",
+                                            params: workspace(workspace_id))))
+      end
+
+      # Move a draft, failed or rejected article to `in_review`; any other
+      # state answers 409.
+      def submit_article(workspace_id, article_id)
+        BlogArticle.new(unwrap(http.request(:post, "/blog/articles/#{article_id}/submit",
+                                            params: workspace(workspace_id))))
+      end
+
+      def reject_article(workspace_id, article_id)
+        BlogArticle.new(unwrap(http.request(:post, "/blog/articles/#{article_id}/reject",
+                                            params: workspace(workspace_id))))
+      end
+
+      def delete_article(workspace_id, article_id)
+        http.request(:delete, "/blog/articles/#{article_id}", params: workspace(workspace_id))
+        nil
+      end
+
+      private
+
+      def workspace(workspace_id)
+        { 'workspace_id' => workspace_id }
+      end
+
+      def patch(path, workspace_id, body)
+        http.request(:patch, path, json: body, params: workspace(workspace_id))
+      end
+
+      def csv(value)
+        value.is_a?(Array) ? value.join(',') : value
+      end
+
+      def date(value)
+        value.respond_to?(:strftime) ? value.strftime('%Y-%m-%d') : value
+      end
+    end
+  end
+end

data/lib/fopost/resources/blogs.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.blogs` — content a connected site already owns.
+    #
+    # Most of this SDK creates content. These calls reach what is already
+    # there: the articles on a WordPress site or a Shopify store's blog, and a
+    # Shopify store's products. Every id here is the platform's own, never a
+    # FoPost id.
+    #
+    # Reads need the `posts` scope. Anything that changes the site needs
+    # `posts` and `publish`, because a change here is visible to the site's own
+    # readers.
+    class Blogs < Base
+      # Blogs the account can write to. Shopify reports every blog on the
+      # store; WordPress reports its one implicit blog, under the id `default`.
+      def list_blogs(account_id)
+        parse_list(RemoteBlog, unwrap(http.get("/accounts/#{account_id}/blogs")))
+      end
+
+      # Articles on the blog, newest first, drafts included.
+      #
+      # `status` is published, draft, pending or scheduled; `q` matches the
+      # title; `limit` is 1 to 50.
+      def list_articles(account_id, blog_id, limit: nil, status: nil, q: nil)
+        params = compact_nil('limit' => limit, 'status' => status, 'q' => q)
+        parse_list(
+          RemoteArticle,
+          unwrap(http.get("/accounts/#{account_id}/blogs/#{blog_id}/articles", params))
+        )
+      end
+
+      def get_article(account_id, blog_id, article_id)
+        RemoteArticle.new(
+          unwrap(http.get("/accounts/#{account_id}/blogs/#{blog_id}/articles/#{article_id}"))
+        )
+      end
+
+      # Write a new article to the blog. Needs the `publish` scope.
+      #
+      # `body` is FoPost body markup; the site's own format is rendered from it.
+      def create_article(account_id, blog_id, title:, body:, excerpt: nil, status: nil,
+                         tags: nil, author_name: nil, image_url: nil)
+        payload = compact_nil(
+          'title' => title,
+          'body' => body,
+          'excerpt' => excerpt,
+          'status' => status,
+          'tags' => tags&.to_a,
+          'author_name' => author_name,
+          'image_url' => image_url
+        )
+        RemoteArticle.new(
+          unwrap(http.post("/accounts/#{account_id}/blogs/#{blog_id}/articles", payload))
+        )
+      end
+
+      # Change the live article in place. Needs the `publish` scope.
+      #
+      # Only the keywords you pass are touched, and the article is addressed by
+      # its own id, so an edit never creates a second post on the site. Pass at
+      # least one field.
+      def update_article(account_id, blog_id, article_id, title: UNSET, body: UNSET,
+                         excerpt: UNSET, status: UNSET, tags: UNSET, author_name: UNSET,
+                         image_url: UNSET)
+        payload = compact_unset(
+          'title' => title,
+          'body' => body,
+          'excerpt' => excerpt,
+          'status' => status,
+          'tags' => UNSET.equal?(tags) ? UNSET : tags&.to_a,
+          'author_name' => author_name,
+          'image_url' => image_url
+        )
+        RemoteArticle.new(
+          unwrap(http.request(
+                   :patch,
+                   "/accounts/#{account_id}/blogs/#{blog_id}/articles/#{article_id}",
+                   json: payload
+                 ))
+        )
+      end
+
+      # Remove the article from the site. Needs `publish`; cannot be undone.
+      def delete_article(account_id, blog_id, article_id)
+        http.delete("/accounts/#{account_id}/blogs/#{blog_id}/articles/#{article_id}")
+        nil
+      end
+
+      # The store's products. `status` is active, draft or archived.
+      def list_products(account_id, limit: nil, status: nil, q: nil)
+        params = compact_nil('limit' => limit, 'status' => status, 'q' => q)
+        parse_list(RemoteProduct, unwrap(http.get("/accounts/#{account_id}/products", params)))
+      end
+
+      # Change a product on the store. Needs `publish`; only what you pass changes.
+      def update_product(account_id, product_id, title: UNSET, description: UNSET,
+                         status: UNSET, tags: UNSET, product_type: UNSET, vendor: UNSET)
+        payload = compact_unset(
+          'title' => title,
+          'description' => description,
+          'status' => status,
+          'tags' => UNSET.equal?(tags) ? UNSET : tags&.to_a,
+          'product_type' => product_type,
+          'vendor' => vendor
+        )
+        RemoteProduct.new(
+          unwrap(http.request(:patch, "/accounts/#{account_id}/products/#{product_id}",
+                              json: payload))
+        )
+      end
+    end
+  end
+end

data/lib/fopost/resources/broadcasts.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.broadcasts` — one message into every conversation the workspace
+    # already has with a segment of its contacts.
+    #
+    # Nothing is sent into a closed messaging window. Messenger and Instagram
+    # take a business-initiated message only within 24 hours of the contact's
+    # last one, so recipients outside it come back skipped with
+    # `window_closed` rather than attempted — which is why the number sent is
+    # often lower than the audience. Telegram, Slack, Bluesky and Reddit have
+    # no window.
+    #
+    # Reading needs the `inbox` scope; {#send} and {#cancel} also need
+    # `publish`.
+    class Broadcasts < Base
+      # One page of broadcasts, newest first. The result is Enumerable over
+      # its items.
+      #
+      # Omit `workspace_id` to span every workspace the key can reach; each
+      # broadcast then carries `workspace_id`.
+      def list(workspace_id: nil, status: nil, page: 1, per_page: 25)
+        body = http.get(
+          '/broadcasts',
+          { 'workspace_id' => workspace_id, 'status' => status, 'page' => page, 'per_page' => per_page }
+        )
+        paged(Broadcast, body)
+      end
+
+      def get(broadcast_id)
+        Broadcast.new(unwrap(http.get("/broadcasts/#{broadcast_id}")))
+      end
+
+      # Create it without sending.
+      #
+      # Give `scheduled_at` to have it go out on its own at that time;
+      # otherwise call {#send}. An omitted `audience` means every contact in
+      # the workspace.
+      def create(workspace_id:, account_id:, name:, text:, media_id: nil, audience: nil, scheduled_at: nil)
+        body = compact_nil(
+          'workspace_id' => workspace_id,
+          'account_id' => account_id,
+          'name' => name,
+          'text' => text,
+          'media_id' => media_id,
+          'audience' => audience,
+          'scheduled_at' => scheduled_at
+        )
+        Broadcast.new(unwrap(http.post('/broadcasts', body)))
+      end
+
+      # Partial update: only what you pass is sent. Only a draft or scheduled
+      # broadcast can be edited.
+      def update(broadcast_id, name: UNSET, text: UNSET, media_id: UNSET, audience: UNSET, scheduled_at: UNSET)
+        body = compact_unset(
+          'name' => name,
+          'text' => text,
+          'media_id' => media_id,
+          'audience' => audience,
+          'scheduled_at' => scheduled_at
+        )
+        Broadcast.new(unwrap(http.request(:patch, "/broadcasts/#{broadcast_id}", json: body)))
+      end
+
+      # Freeze the audience into a recipient list and start sending.
+      #
+      # The returned `recipients` count is how many contacts matched, not how
+      # many will be messaged — the messaging window decides that. Needs the
+      # `publish` scope as well as `inbox`.
+      def send(broadcast_id)
+        as_hash(unwrap(http.post("/broadcasts/#{broadcast_id}/send", {})))
+      end
+
+      # Stop it where it stands. Anyone not yet written to stays unsent;
+      # messages already delivered are not recalled. Needs `publish`.
+      def cancel(broadcast_id)
+        as_hash(unwrap(http.post("/broadcasts/#{broadcast_id}/cancel", {})))
+      end
+
+      # One row per contact, with what became of their message. A skipped row
+      # carries `skip_reason`.
+      def recipients(broadcast_id, status: nil, page: 1, per_page: 50)
+        body = http.get(
+          "/broadcasts/#{broadcast_id}/recipients",
+          { 'status' => status, 'page' => page, 'per_page' => per_page }
+        )
+        paged(BroadcastRecipient, body)
+      end
+
+      # Removes the broadcast and its recipient records. Messages already sent
+      # stay in the conversations they went to.
+      def delete(broadcast_id)
+        http.delete("/broadcasts/#{broadcast_id}")
+        nil
+      end
+
+      private
+
+      # Broadcast lists answer `{data, pagination}`, not `{data, meta}`.
+      def paged(model, body)
+        hash = as_hash(body)
+        raw_meta = hash['pagination']
+        Page.new(
+          items: parse_list(model, hash['data']),
+          meta: ContactPageMeta.new(raw_meta.is_a?(Hash) ? raw_meta : {})
+        )
+      end
+    end
+
+    # `client.sequences` — a series of messages, each a delay after the one
+    # before, walked per enrolled contact.
+    #
+    # The messaging window applies to every step. A step that comes due
+    # outside it is skipped rather than sent, and the enrollment carries on —
+    # so someone can complete a sequence having received only some of its
+    # messages.
+    class Sequences < Base
+      def list(workspace_id: nil, page: 1, per_page: 25)
+        body = http.get('/sequences', { 'workspace_id' => workspace_id, 'page' => page, 'per_page' => per_page })
+        paged(Sequence, body)
+      end
+
+      def get(sequence_id)
+        Sequence.new(unwrap(http.get("/sequences/#{sequence_id}")))
+      end
+
+      # Creating a sequence enrolls nobody.
+      #
+      # Each step is `{ 'delay_hours' => n, 'text' => '...' }`, with
+      # `delay_hours` counted from the previous step.
+      def create(workspace_id:, account_id:, name:, steps:, status: nil)
+        body = compact_nil(
+          'workspace_id' => workspace_id,
+          'account_id' => account_id,
+          'name' => name,
+          'steps' => steps,
+          'status' => status
+        )
+        Sequence.new(unwrap(http.post('/sequences', body)))
+      end
+
+      # Partial update. Pausing stops every enrollment from firing without
+      # ending any of them; resuming picks them up where they stood.
+      def update(sequence_id, name: UNSET, steps: UNSET, status: UNSET)
+        body = compact_unset('name' => name, 'steps' => steps, 'status' => status)
+        Sequence.new(unwrap(http.request(:patch, "/sequences/#{sequence_id}", json: body)))
+      end
+
+      # Put contacts on the sequence, by id or by the same audience filter a
+      # broadcast takes.
+      #
+      # Re-enrolling someone restarts their walk from the first step rather
+      # than running two in parallel. Needs `publish` as well as `inbox`.
+      def enroll(sequence_id, contact_ids: nil, audience: nil)
+        body = compact_nil('contact_ids' => contact_ids, 'audience' => audience)
+        as_hash(unwrap(http.post("/sequences/#{sequence_id}/enroll", body)))
+      end
+
+      # Nothing further fires for them. Needs `publish`.
+      def unenroll(sequence_id, contact_ids)
+        as_hash(unwrap(http.post("/sequences/#{sequence_id}/unenroll", { 'contact_ids' => contact_ids })))
+      end
+
+      # Who is on it, what step they are at, and when the next one is due.
+      def enrollments(sequence_id, page: 1, per_page: 50)
+        body = http.get("/sequences/#{sequence_id}/enrollments", { 'page' => page, 'per_page' => per_page })
+        paged(Enrollment, body)
+      end
+
+      # Removes the sequence and every enrollment on it.
+      def delete(sequence_id)
+        http.delete("/sequences/#{sequence_id}")
+        nil
+      end
+
+      private
+
+      def paged(model, body)
+        hash = as_hash(body)
+        raw_meta = hash['pagination']
+        Page.new(
+          items: parse_list(model, hash['data']),
+          meta: ContactPageMeta.new(raw_meta.is_a?(Hash) ? raw_meta : {})
+        )
+      end
+    end
+  end
+end