fopost 0.1.0 → 0.3.0

data/lib/fopost/resources/inbox.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.inbox` — comments, mentions, reviews and direct messages on connected
+    # accounts. Every method needs the `inbox` scope.
+    class Inbox < Base
+      # One page of items, newest first. The result is Enumerable over its items.
+      #
+      # `type` is comment, mention, review or dm; `state` is unread, read, resolved or
+      # snoozed; `sort` is newest, oldest or unanswered.
+      def list(workspace_id: nil, type: nil, state: nil, platform: nil, account_id: nil, post_id: nil,
+               post_external_id: nil, conversation_id: nil, direction: nil, q: nil, sort: nil,
+               page: 1, per_page: 25)
+        body = http.get(
+          '/inbox',
+          {
+            'workspace_id' => workspace_id,
+            'type' => type,
+            'state' => state,
+            'platform' => platform,
+            'account_id' => account_id,
+            'post_id' => post_id,
+            'post_external_id' => post_external_id,
+            'conversation_id' => conversation_id,
+            'direction' => direction,
+            'q' => q,
+            'sort' => sort,
+            'page' => page,
+            'per_page' => per_page
+          }
+        )
+        page_of(InboxItem, body)
+      end
+
+      # One row per post with comments; `kind: 'mentions'` for posts the
+      # account was tagged in, `kind: 'reviews'` for one row per review left
+      # on the business, each carrying its rating.
+      def threads(workspace_id: nil, kind: nil, platform: nil, account_id: nil, state: nil, q: nil,
+                  sort: nil, page: 1, per_page: 25)
+        body = http.get(
+          '/inbox/posts',
+          {
+            'workspace_id' => workspace_id,
+            'kind' => kind,
+            'platform' => platform,
+            'account_id' => account_id,
+            'state' => state,
+            'q' => q,
+            'sort' => sort,
+            'page' => page,
+            'per_page' => per_page
+          }
+        )
+        page_of(InboxThread, body)
+      end
+
+      # One row per DM thread, latest first.
+      def conversations(workspace_id: nil, platform: nil, account_id: nil, state: nil, q: nil, sort: nil,
+                        page: 1, per_page: 25)
+        body = http.get(
+          '/inbox/conversations',
+          {
+            'workspace_id' => workspace_id,
+            'platform' => platform,
+            'account_id' => account_id,
+            'state' => state,
+            'q' => q,
+            'sort' => sort,
+            'page' => page,
+            'per_page' => per_page
+          }
+        )
+        page_of(InboxConversation, body)
+      end
+
+      def unread_count(workspace_id: nil)
+        body = http.get('/inbox/unread-count', { 'workspace_id' => workspace_id })
+        count = body.is_a?(Hash) ? body['count'] : nil
+        count.is_a?(Integer) ? count : 0
+      end
+
+      # Every active account, flagged with whether comments and DMs can be read for it.
+      def accounts(workspace_id: nil)
+        parse_list(InboxAccount, unwrap(http.get('/inbox/accounts', { 'workspace_id' => workspace_id })))
+      end
+
+      def platforms
+        parse_list(InboxPlatform, unwrap(http.get('/inbox/platforms')))
+      end
+
+      # Mark a whole comment thread or DM thread read. Returns how many items changed.
+      def mark_thread_read(workspace_id:, account_id:, post_external_id: nil, conversation_id: nil)
+        body = compact_nil(
+          'workspace_id' => workspace_id,
+          'account_id' => account_id,
+          'post_external_id' => post_external_id,
+          'conversation_id' => conversation_id
+        )
+        result = unwrap(http.post('/inbox/read', body))
+        updated = result.is_a?(Hash) ? result['updated'] : nil
+        updated.is_a?(Integer) ? updated : 0
+      end
+
+      # Poll every inbox-capable account in the workspace now.
+      def refresh(workspace_id:)
+        InboxRefreshResult.new(unwrap(http.post('/inbox/refresh', { 'workspace_id' => workspace_id })))
+      end
+
+      # Set the item's state to unread, read, resolved or snoozed. A snooze
+      # needs `snoozed_until` in the future.
+      def update(item_id, state:, snoozed_until: nil)
+        body = compact_nil('state' => state, 'snoozedUntil' => iso8601(snoozed_until))
+        InboxItem.new(unwrap(http.request(:patch, "/inbox/#{item_id}", json: body)))
+      end
+
+      # Edit a comment the account wrote, on the platform. Needs `publish`.
+      def edit_comment(item_id, text:)
+        InboxItem.new(unwrap(http.request(:patch, "/inbox/#{item_id}", json: { 'text' => text })))
+      end
+
+      # Send the reply on the platform as the connected account. `text` may be
+      # left out when `media_ids` is given; `media_ids` and `quick_replies` need `publish`.
+      def reply(item_id, text: nil, media_ids: nil, quick_replies: nil)
+        body = compact_nil('text' => text, 'media_ids' => media_ids, 'quick_replies' => quick_replies)
+        InboxReplyResult.new(unwrap(http.post("/inbox/#{item_id}/reply", body)))
+      end
+
+      def hide(item_id)
+        InboxItem.new(unwrap(http.post("/inbox/#{item_id}/hide")))
+      end
+
+      def unhide(item_id)
+        InboxItem.new(unwrap(http.post("/inbox/#{item_id}/unhide")))
+      end
+
+      # Delete the comment on the platform, or our own reply (that also needs `publish`).
+      def delete(item_id)
+        http.delete("/inbox/#{item_id}")
+        nil
+      end
+
+      # Like the item (an upvote on Reddit, a favourite on Mastodon). Needs `publish`.
+      def like(item_id)
+        InboxItem.new(unwrap(http.post("/inbox/#{item_id}/like")))
+      end
+
+      def unlike(item_id)
+        InboxItem.new(unwrap(http.post("/inbox/#{item_id}/unlike")))
+      end
+
+      # Vote up or down where the network ranks by votes (Reddit), where `can_vote`
+      # is true. `direction` is 'up', 'down', or 'none' to take an earlier vote
+      # back. An upvote is the same call a like makes, so `liked` moves with it.
+      # Needs `publish`.
+      def vote(item_id, direction)
+        InboxItem.new(unwrap(http.post("/inbox/#{item_id}/vote", { 'direction' => direction })))
+      end
+
+      # Pin our own comment. Needs `publish`.
+      def pin(item_id)
+        InboxItem.new(unwrap(http.post("/inbox/#{item_id}/pin")))
+      end
+
+      def unpin(item_id)
+        InboxItem.new(unwrap(http.post("/inbox/#{item_id}/unpin")))
+      end
+
+      # React to a DM with an emoji; `nil` removes ours. Needs `publish`.
+      def react(item_id, reaction:)
+        InboxItem.new(unwrap(http.post("/inbox/#{item_id}/react", { 'reaction' => reaction })))
+      end
+
+      # Open a DM: by `handle` from `account_id`, or as a private reply to the
+      # inbox comment `comment_id`. Needs `publish`.
+      def start_conversation(text:, account_id: nil, handle: nil, comment_id: nil, media_ids: nil)
+        body = compact_nil(
+          'account_id' => account_id,
+          'handle' => handle,
+          'comment_id' => comment_id,
+          'text' => text,
+          'media_ids' => media_ids
+        )
+        InboxStartedConversation.new(unwrap(http.post('/inbox/conversations', body)))
+      end
+
+      # Show or clear the typing indicator in a DM thread. Returns whether it is on. Needs `publish`.
+      def set_typing(conversation_id, account_id:, on: true)
+        body = { 'account_id' => account_id, 'on' => on }
+        as_hash(unwrap(http.post("/inbox/conversations/#{conversation_id}/typing", body)))['typing']
+      end
+
+      # Pass a Messenger thread to another Meta app, or take it back without an `app_id`.
+      def handover(conversation_id, account_id:, app_id: nil, metadata: nil)
+        body = { 'account_id' => account_id }
+        body['app_id'] = app_id unless app_id.nil?
+        body['metadata'] = metadata unless metadata.nil?
+        InboxHandover.new(unwrap(http.post("/inbox/conversations/#{conversation_id}/handover", body)))
+      end
+
+      # Replies an automation or the agent drafted that a person still has to send.
+      def approvals(workspace_id: nil)
+        parse_list(InboxApproval, unwrap(http.get('/inbox/approvals', { 'workspace_id' => workspace_id })))
+      end
+
+      # Send the draft, or `text` in its place.
+      def approve_reply(approval_id, text: nil)
+        as_hash(unwrap(http.post("/inbox/approvals/#{approval_id}/approve", compact_nil('text' => text))))
+      end
+
+      def reject_reply(approval_id)
+        as_hash(unwrap(http.post("/inbox/approvals/#{approval_id}/reject")))
+      end
+
+      private
+
+      def page_of(model, body)
+        items = parse_list(model, 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/knowledge.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.knowledge` — what the workspace has told FoPost about itself.
+    #
+    # A source is an FAQ, a note, a page on your own site, or a plain-text/CSV
+    # item from the media library. Retrieval over these is what grounds a
+    # drafted inbox reply in your own answers instead of an invented one.
+    # Needs the `inbox` scope.
+    class Knowledge < Base
+      def list(workspace_id: nil)
+        parse_list(
+          KnowledgeSource,
+          unwrap(http.get('/knowledge/sources', { 'workspace_id' => workspace_id }))
+        )
+      end
+
+      # Adds a source and queues it for indexing, so it comes back `pending`.
+      #
+      # `kind` is `faq`, `text`, `url` or `file`. An `faq` or `text` source
+      # needs `content`, a `url` source needs `url`, and a `file` source needs
+      # `media_id` pointing at a plain-text or CSV item in the same workspace.
+      def create(kind:, title:, content: nil, url: nil, media_id: nil, brand_voice_id: nil,
+                 workspace_id: nil)
+        body = compact_nil(
+          'kind' => kind,
+          'title' => title,
+          'content' => content,
+          'url' => url,
+          'media_id' => media_id,
+          'brand_voice_id' => brand_voice_id,
+          'workspace_id' => workspace_id
+        )
+        KnowledgeSource.new(unwrap(http.post('/knowledge/sources', body)))
+      end
+
+      # Partial update. Changing the content or the URL returns the source to
+      # `pending` and re-indexes it.
+      def update(source_id, title: UNSET, content: UNSET, url: UNSET, brand_voice_id: UNSET)
+        body = compact_unset(
+          'title' => title,
+          'content' => content,
+          'url' => url,
+          'brand_voice_id' => brand_voice_id
+        )
+        KnowledgeSource.new(unwrap(http.patch("/knowledge/sources/#{source_id}", body)))
+      end
+
+      # Removes the source and every passage indexed from it.
+      def delete(source_id)
+        http.delete("/knowledge/sources/#{source_id}")
+        nil
+      end
+
+      # Reads the source again — a `url` source is re-fetched. Returns once queued.
+      def sync(source_id)
+        http.post("/knowledge/sources/#{source_id}/sync", {})
+        nil
+      end
+
+      # The passages closest to a question, best first. Empty is the honest
+      # answer when nothing stored answers it.
+      def search(q, top_k: nil, brand_voice_id: nil, workspace_id: nil)
+        parse_list(KnowledgeMatch, unwrap(http.get('/knowledge/search', {
+                                                     'q' => q,
+                                                     'top_k' => top_k,
+                                                     'brand_voice_id' => brand_voice_id,
+                                                     'workspace_id' => workspace_id
+                                                   })))
+      end
+    end
+  end
+end

data/lib/fopost/resources/media.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.media` — direct uploads to the media library.
+    #
+    # A direct upload is three steps: {#presign} reserves a slot, the bytes go
+    # straight to `upload_url` with the returned headers, and {#complete}
+    # turns the slot into a library item. {#upload_direct} does all three.
+    class Media < Base
+      # What a multipart request carries per file when `/media/limits` cannot be read.
+      DEFAULT_MULTIPART_MAX_FILE_BYTES = 100 * 1024 * 1024
+
+      # The upload ceilings for the account, by connected accounts or add-on.
+      def limits(workspace_id: nil)
+        UploadLimits.new(unwrap(http.get('/media/limits', { 'workspaceId' => workspace_id })))
+      end
+
+      # Reserve an upload slot. `size` is the exact byte count of the file, up
+      # to the account's `max_file_bytes`.
+      def presign(workspace_id:, filename:, mime_type:, size:, folder_id: nil, origin: nil, brand_role: nil,
+                  brand_voice_id: nil, person_consent: nil)
+        body = {
+          'workspaceId' => workspace_id,
+          'filename' => filename,
+          'mimeType' => mime_type,
+          'size' => size
+        }
+        body.merge!(
+          compact_nil(
+            'folderId' => folder_id,
+            'origin' => origin,
+            'brandRole' => brand_role,
+            'brandVoiceId' => brand_voice_id,
+            'personConsent' => person_consent
+          )
+        )
+        PresignedUpload.new(unwrap(http.post('/media/presign', body)))
+      end
+
+      # Turn an uploaded slot into a media item.
+      def complete(upload_id)
+        MediaItem.new(unwrap(http.post("/media/presign/#{upload_id}/complete")))
+      end
+
+      # Presign, PUT `data` (a binary String), and complete in one call.
+      def upload_direct(workspace_id:, filename:, mime_type:, data:, **presign_options)
+        upload = presign(workspace_id: workspace_id, filename: filename, mime_type: mime_type,
+                         size: data.bytesize, **presign_options)
+        headers = upload.headers.merge('Content-Length' => data.bytesize.to_s)
+        http.put_raw(upload.upload_url, data, headers)
+        complete(upload.upload_id)
+      end
+    end
+  end
+end

data/lib/fopost/resources/posts.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Fopost
   module Resources
     # `client.posts` — create, schedule, publish, and inspect posts.
@@ -66,9 +68,14 @@ module Fopost
       # Create a draft or a scheduled post.
       #
       # `status` is "draft" or "scheduled"; a scheduled post needs `schedule_at`.
-      # To send a post out now, create it and call {#publish}.
-      def create(workspace_id:, content:, accounts: [], status: 'draft', schedule_at: nil,
-                 labels: nil, title: nil, summary: nil, content_type: nil, settings: nil, **extra)
+      # To send a post out now, create it and call {#publish}. `account_group_id`
+      # adds that group's accounts to `accounts`, so `accounts` may be left empty.
+      #
+      # `files` (paths, IOs, or `{ filename:, io:/data:, mime_type: }` hashes) are
+      # stored in the library and attached to the first block. Files over the
+      # multipart ceiling go through direct upload; the result is the same.
+      def create(workspace_id:, content:, accounts: [], account_group_id: nil, status: 'draft', schedule_at: nil,
+                 labels: nil, title: nil, summary: nil, content_type: nil, settings: nil, files: nil, **extra)
         body = {
           'workspace_id' => workspace_id,
           'status' => status,
@@ -77,6 +84,7 @@ module Fopost
         }
         body.merge!(
           compact_nil(
+            'account_group_id' => account_group_id,
             'schedule_at' => iso8601(schedule_at),
             'labels' => labels&.to_a,
             'title' => title,
@@ -87,6 +95,15 @@ module Fopost
         )
         body.merge!(stringify(extra))
 
+        parts = file_parts(files)
+        return Post.new(unwrap(http.post('/posts', body))) if parts.empty?
+
+        if multipart_fits?(parts, workspace_id)
+          fields = { 'post' => JSON.generate(body) }
+          return Post.new(unwrap(http.post_multipart('/posts', fields: fields, parts: multipart_parts(parts))))
+        end
+
+        attach_media(body['content'], upload_parts(workspace_id, parts))
         Post.new(unwrap(http.post('/posts', body)))
       end
 
@@ -94,7 +111,7 @@ module Fopost
       # to clear a field.
       def update(post_id, content: UNSET, accounts: UNSET, status: UNSET, schedule_at: UNSET,
                  labels: UNSET, title: UNSET, summary: UNSET, content_type: UNSET,
-                 settings: UNSET, **extra)
+                 settings: UNSET, files: nil, **extra)
         body = compact_unset(
           'content' => UNSET.equal?(content) ? UNSET : normalize_content(content),
           'accounts' => UNSET.equal?(accounts) ? UNSET : normalize_accounts(accounts),
@@ -108,6 +125,19 @@ module Fopost
         )
         body.merge!(stringify(extra))
 
+        parts = file_parts(files)
+        return Post.new(unwrap(http.put("/posts/#{post_id}", body))) if parts.empty?
+
+        if multipart_fits?(parts, nil)
+          fields = { 'post' => JSON.generate(body) }
+          multipart = http.put_multipart("/posts/#{post_id}", fields: fields, parts: multipart_parts(parts))
+          return Post.new(unwrap(multipart))
+        end
+
+        # The direct path needs the workspace, and the current blocks when none were given.
+        existing = get(post_id)
+        body['content'] = normalize_content(existing.content) unless body.key?('content')
+        attach_media(body['content'], upload_parts(existing.workspace_id, parts))
         Post.new(unwrap(http.put("/posts/#{post_id}", body)))
       end
 
@@ -180,6 +210,47 @@ module Fopost
       def stringify(hash)
         hash.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
       end
+
+      def file_parts(files)
+        Array(files).map { |file| FilePart.from(file) }
+      end
+
+      # One multipart request when every file fits its per-file ceiling.
+      def multipart_fits?(parts, workspace_id)
+        ceiling = begin
+          media.limits(workspace_id: workspace_id).multipart_max_file_bytes
+        rescue Error
+          nil
+        end
+        ceiling = Media::DEFAULT_MULTIPART_MAX_FILE_BYTES unless ceiling.is_a?(Integer)
+        parts.all? { |part| part.size <= ceiling }
+      end
+
+      def multipart_parts(parts)
+        parts.map do |part|
+          HTTP::Multipart::Part.new(name: 'files', filename: part.filename, mime_type: part.mime_type,
+                                    data: part.data)
+        end
+      end
+
+      def upload_parts(workspace_id, parts)
+        parts.map do |part|
+          item = media.upload_direct(workspace_id: workspace_id, filename: part.filename,
+                                     mime_type: part.mime_type, data: part.data)
+          compact_nil('type' => part.media_type, 'name' => item.name || part.filename, 'url' => item.url,
+                      'size' => item.size || part.size)
+        end
+      end
+
+      def attach_media(blocks, items)
+        blocks << {} if blocks.empty?
+        first = blocks.first
+        first['media'] = Array(first['media']) + items
+      end
+
+      def media
+        @media ||= Media.new(http)
+      end
     end
   end
 end

data/lib/fopost/resources/validate.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.validate` — check a draft, its length, or a media URL against
+    # platform rules before creating a post. Nothing is stored server-side.
+    class Validate < Base
+      # Full preflight: blockers per platform plus advisory signals.
+      def post(platforms:, content: nil, media: nil)
+        body = compact_nil(
+          'content' => content,
+          'media' => media&.map { |item| item.transform_keys(&:to_s) },
+          'platforms' => platforms.to_a
+        )
+        ValidatePostResult.new(unwrap(http.post('/validate/post', body)))
+      end
+
+      # Text length against each platform's limit.
+      def length(text:, platforms:)
+        body = { 'text' => text, 'platforms' => platforms.to_a }
+        ValidateLengthResult.new(unwrap(http.post('/validate/length', body)))
+      end
+
+      # Fetch a public URL and check the file. Answers 200 even when a check fails.
+      def media(url:)
+        ValidateMediaResult.new(unwrap(http.post('/validate/media', { 'url' => url })))
+      end
+
+      # Whether a subreddit exists and takes a post from this Reddit account. The
+      # check runs with the account's own token, so `account_id` is required.
+      def subreddit(account_id:, name:)
+        params = { 'account_id' => account_id, 'name' => name }
+        SubredditCheck.new(unwrap(http.get('/validate/subreddit', params)))
+      end
+    end
+  end
+end