fopost 0.2.0 → 0.3.0

data/lib/fopost/resources/inbox.rb

@@ -2,12 +2,12 @@
 
 module Fopost
   module Resources
-    # `client.inbox` — comments, mentions and direct messages on connected
+    # `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 or dm; `state` is unread, read, resolved or
+      # `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,
@@ -34,7 +34,8 @@ module Fopost
       end
 
       # One row per post with comments; `kind: 'mentions'` for posts the
-      # account was tagged in.
+      # 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(
@@ -113,9 +114,16 @@ module Fopost
         InboxItem.new(unwrap(http.request(:patch, "/inbox/#{item_id}", json: body)))
       end
 
-      # Send the reply on the platform as the connected account.
-      def reply(item_id, text:)
-        InboxReplyResult.new(unwrap(http.post("/inbox/#{item_id}/reply", { 'text' => text })))
+      # 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)
@@ -126,12 +134,70 @@ module Fopost
         InboxItem.new(unwrap(http.post("/inbox/#{item_id}/unhide")))
       end
 
-      # Delete the comment on the platform.
+      # 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 })))

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

data/lib/fopost/resources/whatsapp.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Fopost
+  module Resources
+    # `client.whatsapp` — a WhatsApp Business connection.
+    #
+    # The platform owns templates, flows, the profile and the commerce settings,
+    # so every method here is a live read or write against the customer's own
+    # WhatsApp Business Account. All of it answers 503 until WhatsApp is set up.
+    class Whatsapp < Base
+      # ─── Profile ─────────────────────────────────────────────────
+
+      def profile(account_id)
+        WhatsappProfile.new(unwrap(http.get("/accounts/#{account_id}/whatsapp/profile")))
+      end
+
+      def update_profile(account_id, about: UNSET, address: UNSET, description: UNSET,
+                         vertical: UNSET, websites: UNSET, profile_picture_media_id: UNSET)
+        body = compact_unset(
+          'about' => about,
+          'address' => address,
+          'description' => description,
+          'vertical' => vertical,
+          'websites' => websites,
+          'profile_picture_media_id' => profile_picture_media_id
+        )
+        WhatsappProfile.new(unwrap(http.request(:patch, "/accounts/#{account_id}/whatsapp/profile", json: body)))
+      end
+
+      # A review, not a write: the number keeps its old name until it passes.
+      def request_display_name(account_id, display_name)
+        body = { 'display_name' => display_name }
+        as_hash(unwrap(http.post("/accounts/#{account_id}/whatsapp/profile/display-name", body)))
+      end
+
+      def set_username(account_id, username)
+        body = { 'username' => username }
+        WhatsappProfile.new(unwrap(http.put("/accounts/#{account_id}/whatsapp/profile/username", body)))
+      end
+
+      # ─── Templates ───────────────────────────────────────────────
+
+      def templates(account_id, after: nil)
+        params = compact_nil('after' => after)
+        parse_list(WhatsappTemplate, unwrap(http.get("/accounts/#{account_id}/whatsapp/templates", params)))
+      end
+
+      # The platform's pre-written templates, for adapting instead of drafting.
+      def template_library(account_id, search: nil)
+        params = compact_nil('search' => search)
+        body = unwrap(http.get("/accounts/#{account_id}/whatsapp/templates/library", params))
+        body.is_a?(Array) ? body : []
+      end
+
+      def template(account_id, template_id)
+        WhatsappTemplate.new(unwrap(http.get("/accounts/#{account_id}/whatsapp/templates/#{template_id}")))
+      end
+
+      # Files a template for review; the result carries the status it was given.
+      def create_template(account_id, name:, language:, category:, components:,
+                          allow_category_change: nil)
+        body = compact_nil(
+          'name' => name,
+          'language' => language,
+          'category' => category,
+          'components' => components.map { |c| c.transform_keys(&:to_s) },
+          'allow_category_change' => allow_category_change
+        )
+        WhatsappTemplate.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/templates", body)))
+      end
+
+      def import_template(account_id, library_template_name:, name:, language:, category:,
+                          library_template_button_inputs: nil)
+        body = compact_nil(
+          'library_template_name' => library_template_name,
+          'name' => name,
+          'language' => language,
+          'category' => category,
+          'library_template_button_inputs' => library_template_button_inputs
+        )
+        WhatsappTemplate.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/templates/import", body)))
+      end
+
+      def update_template(account_id, template_id, category: nil, components: nil)
+        body = compact_nil('category' => category, 'components' => components)
+        path = "/accounts/#{account_id}/whatsapp/templates/#{template_id}"
+        WhatsappTemplate.new(unwrap(http.request(:patch, path, json: body)))
+      end
+
+      # The name is required: it is what the platform deletes by.
+      def delete_template(account_id, template_id, name:)
+        query = URI.encode_www_form('name' => name)
+        as_hash(unwrap(http.delete("/accounts/#{account_id}/whatsapp/templates/#{template_id}?#{query}")))
+      end
+
+      # ─── Groups ──────────────────────────────────────────────────
+
+      def groups(account_id)
+        parse_list(WhatsappGroup, unwrap(http.get("/accounts/#{account_id}/whatsapp/groups")))
+      end
+
+      # Participation is invite-only: send the invite link, there is no add.
+      def create_group(account_id, subject:, description: nil)
+        body = compact_nil('subject' => subject, 'description' => description)
+        WhatsappGroup.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/groups", body)))
+      end
+
+      def group(account_id, group_id)
+        WhatsappGroup.new(unwrap(http.get("/accounts/#{account_id}/whatsapp/groups/#{group_id}")))
+      end
+
+      def update_group(account_id, group_id, subject: nil, description: nil)
+        body = compact_nil('subject' => subject, 'description' => description)
+        path = "/accounts/#{account_id}/whatsapp/groups/#{group_id}"
+        WhatsappGroup.new(unwrap(http.request(:patch, path, json: body)))
+      end
+
+      def delete_group(account_id, group_id)
+        as_hash(unwrap(http.delete("/accounts/#{account_id}/whatsapp/groups/#{group_id}")))
+      end
+
+      def group_invite_link(account_id, group_id)
+        body = as_hash(unwrap(http.get("/accounts/#{account_id}/whatsapp/groups/#{group_id}/invite-link")))
+        body['inviteLink']
+      end
+
+      # Issues a new link and invalidates the old one.
+      def reset_group_invite_link(account_id, group_id)
+        body = as_hash(unwrap(http.post("/accounts/#{account_id}/whatsapp/groups/#{group_id}/invite-link")))
+        body['inviteLink']
+      end
+
+      def remove_group_participants(account_id, group_id, users)
+        path = "/accounts/#{account_id}/whatsapp/groups/#{group_id}/participants"
+        as_hash(unwrap(http.delete(path, { 'users' => users.to_a })))
+      end
+
+      # ─── Blocking ────────────────────────────────────────────────
+
+      def blocked(account_id, after: nil)
+        params = compact_nil('after' => after)
+        body = unwrap(http.get("/accounts/#{account_id}/whatsapp/block", params))
+        body.is_a?(Array) ? body : []
+      end
+
+      def block_users(account_id, users)
+        body = { 'users' => users.to_a }
+        WhatsappBlockResult.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/block", body)))
+      end
+
+      def unblock_users(account_id, users)
+        body = { 'users' => users.to_a }
+        WhatsappBlockResult.new(unwrap(http.delete("/accounts/#{account_id}/whatsapp/block", body)))
+      end
+
+      # ─── Commerce ────────────────────────────────────────────────
+
+      def commerce_settings(account_id)
+        WhatsappCommerceSettings.new(unwrap(http.get("/accounts/#{account_id}/whatsapp/commerce")))
+      end
+
+      def update_commerce_settings(account_id, cart_enabled: nil, catalog_visible: nil)
+        body = compact_nil('is_cart_enabled' => cart_enabled, 'is_catalog_visible' => catalog_visible)
+        path = "/accounts/#{account_id}/whatsapp/commerce"
+        WhatsappCommerceSettings.new(unwrap(http.request(:patch, path, json: body)))
+      end
+
+      def link_catalog(account_id, catalog_id)
+        body = { 'catalog_id' => catalog_id }
+        path = "/accounts/#{account_id}/whatsapp/commerce/catalog"
+        WhatsappCommerceSettings.new(unwrap(http.post(path, body)))
+      end
+
+      # ─── Flows ───────────────────────────────────────────────────
+
+      def flows(account_id)
+        parse_list(WhatsappFlow, unwrap(http.get("/accounts/#{account_id}/whatsapp/flows")))
+      end
+
+      def flow(account_id, flow_id)
+        WhatsappFlow.new(unwrap(http.get("/accounts/#{account_id}/whatsapp/flows/#{flow_id}")))
+      end
+
+      def create_flow(account_id, name:, categories:, endpoint_uri: nil, clone_flow_id: nil)
+        body = compact_nil(
+          'name' => name,
+          'categories' => categories.to_a,
+          'endpoint_uri' => endpoint_uri,
+          'clone_flow_id' => clone_flow_id
+        )
+        WhatsappFlow.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/flows", body)))
+      end
+
+      def update_flow(account_id, flow_id, name: nil, categories: nil, endpoint_uri: nil)
+        body = compact_nil('name' => name, 'categories' => categories, 'endpoint_uri' => endpoint_uri)
+        path = "/accounts/#{account_id}/whatsapp/flows/#{flow_id}"
+        WhatsappFlow.new(unwrap(http.request(:patch, path, json: body)))
+      end
+
+      # Drafts only; a published flow is deprecated instead.
+      def delete_flow(account_id, flow_id)
+        as_hash(unwrap(http.delete("/accounts/#{account_id}/whatsapp/flows/#{flow_id}")))
+      end
+
+      # The platform answers with its validation errors rather than refusing.
+      def upload_flow_json(account_id, flow_id, flow_json)
+        body = { 'flow_json' => flow_json }
+        path = "/accounts/#{account_id}/whatsapp/flows/#{flow_id}/json"
+        WhatsappFlowJsonResult.new(unwrap(http.put(path, body)))
+      end
+
+      def publish_flow(account_id, flow_id)
+        WhatsappFlow.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/flows/#{flow_id}/publish")))
+      end
+
+      def deprecate_flow(account_id, flow_id)
+        WhatsappFlow.new(unwrap(http.post("/accounts/#{account_id}/whatsapp/flows/#{flow_id}/deprecate")))
+      end
+
+      def flow_responses(account_id)
+        path = "/accounts/#{account_id}/whatsapp/flows/responses"
+        parse_list(WhatsappFlowResponse, unwrap(http.get(path)))
+      end
+
+      def encryption_key_status(account_id)
+        path = "/accounts/#{account_id}/whatsapp/flows/encryption-key"
+        WhatsappEncryptionKeyStatus.new(unwrap(http.get(path)))
+      end
+
+      # The public half only; the private half stays with the customer.
+      def set_encryption_key(account_id, business_public_key)
+        body = { 'business_public_key' => business_public_key }
+        path = "/accounts/#{account_id}/whatsapp/flows/encryption-key"
+        WhatsappEncryptionKeyStatus.new(unwrap(http.put(path, body)))
+      end
+
+      # ─── Account state and sandbox ───────────────────────────────
+
+      def account_events(account_id)
+        as_hash(unwrap(http.get("/accounts/#{account_id}/whatsapp/events")))
+      end
+
+      def sandbox_sessions(workspace_id:)
+        params = { 'workspaceId' => workspace_id }
+        parse_list(WhatsappSandboxSession, unwrap(http.get('/whatsapp/sandbox/sessions', params)))
+      end
+
+      # Sends a template from the platform-owned test number; needs the publish scope.
+      def create_sandbox_session(workspace_id:, phone_number:)
+        body = { 'workspaceId' => workspace_id, 'phoneNumber' => phone_number }
+        WhatsappSandboxSession.new(unwrap(http.post('/whatsapp/sandbox/sessions', body)))
+      end
+    end
+  end
+end

data/lib/fopost/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fopost
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end