nohead 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68e5883cc4d13b186ac691a79aeb84b5a10462c2e350ddbffe17cd832ffc6d30
-  data.tar.gz: 702a971c87efbda7fdc438410984f93fd7f315ca655958e6510b6027ca970089
+  metadata.gz: 614f02b14cf5307614caf01ae06d458d770bff423c34d567d0fe8f7924467298
+  data.tar.gz: 052d1089ecc31f984b4d1e143638b4b26b8d393c1a8eac9764a5e6df8a76d364
 SHA512:
-  metadata.gz: f8f38c6c8844668251282d375d1f20373621460aefb0ab340beffa29c8bb000fc38025b17746fae7b7dde10f7007dee92806240e3f0de996774e7ebfeef6e234
-  data.tar.gz: 387779fad0fd93d5eb68e4956e434ee2eedbb70ad0f00f1fbc80f23b8d34891eaf8338d27c6b97927432951846d85aa7ea921065b741043a185bf2903a1d03d4
+  metadata.gz: 432a87faa068fb1719a38ba559520de892c0cf48abc0783b1ba1c0114d6fbe252b5cffd72c0d89d40de323c563e7c528334796ff7da0695ff2b48b2636fa46da
+  data.tar.gz: 1383b012a30ec74972234dcda1c61f62f75e948929c9f8c6d14e52fcd7245595521c2e00426b0e0030a4b3887dc77231c2808ec5ef0390aa8818b8f655216c2e

data/CHANGELOG.md

@@ -5,6 +5,15 @@ Changes to the `nohead` gem that you can notice. Versions follow
 releases; a change that could break your code is a major one. Each release's
 section is its GitHub release's notes.
 
+## 0.10.0
+
+- Rich text fields read as HTML or Markdown with `rich_text:` (`"document"`,
+  the default, `"html"` or `"markdown"`), on `Nohead::Client.new` and
+  `with_options` for every call, or on a call: the methods that return
+  records or drafts take it, and a call's value wins over the client's. The
+  field's value is then a string, in records embedded with `expand:` too.
+  Writing Markdown already worked: `data` is sent as it is.
+
 ## 0.9.0
 
 - **Breaking:** the client no longer reads `NOHEAD_API_URL`: a stray value

data/README.md

@@ -20,6 +20,7 @@ end
 - [Configuration](#configuration)
 - [Records](#records)
 - [Drafts](#drafts)
+- [Rich text](#rich-text)
 - [Pagination](#pagination)
 - [Errors](#errors)
 - [Retries and idempotency](#retries-and-idempotency)
@@ -63,10 +64,11 @@ nohead = Nohead::Client.new(
 | `headers:` | `{}` | Added to every request. |
 | `warnings:` | `true` | Warns about deprecated operations and plan usage, once each. |
 | `on_retry:` | | Called before each retry's wait. See [retries](#retries-and-idempotency). |
+| `rich_text:` | `"document"` | How rich text fields read: see [rich text](#rich-text). |
 
 An empty string is the same as leaving an option out (`api_key: ""` reads `NOHEAD_API_KEY`, `base_url: ""` uses `https://api.nohead.io`). The base URL comes only from `base_url:`, never from the environment. A `base_url:` that isn't `http` or `https` raises `Nohead::Error`.
 
-`with_options` gives a copy of the client with other settings (`timeout:`, `max_retries:`, `headers:`, added to the client's, and `on_retry:`), sharing its project lookup:
+`with_options` gives a copy of the client with other settings (`timeout:`, `max_retries:`, `headers:`, added to the client's, `on_retry:` and `rich_text:`), sharing its project lookup:
 
 ```ruby
 nohead.with_options(timeout: 5, max_retries: 0).records.get(id)
@@ -113,6 +115,24 @@ nohead.drafts.merge(draft.id) # or drafts.schedule(draft.id, merge_at: ...)
 - `records.drafts(id)` lists a record's draft, and `drafts.list(collection)` a collection's.
 - `drafts.discard` deletes one for good.
 
+## Rich text
+
+A rich text field is written as Markdown or as a document (ProseMirror JSON), and reads as a document unless you ask for HTML or Markdown with `rich_text:`, for the whole client or for one call:
+
+```ruby
+nohead.records.create("posts", data: { body: "## Hello\n\nWritten in **Markdown**." })
+
+nohead = Nohead::Client.new(rich_text: "html")
+nohead.records.get(id).data["body"] # an HTML string
+nohead.records.get(id, rich_text: "markdown").data["body"] # a Markdown string
+```
+
+- With `"html"` or `"markdown"`, the field's value is a string instead of the document, in records embedded with `expand:` too. `"document"` is the default.
+- The methods that return records or drafts take `rich_text:`; a call's value wins over the client's, and other methods never send it.
+- HTML has every text and attribute escaped, ready to put in a page. Images come with their URLs, so they need no `expand:`.
+- Record history (`records.revisions.list` and `get`) and webhook events keep documents.
+- A string you write is read as Markdown, so write back Markdown or the document, never the HTML: with `rich_text: "html"` on the client, writes answer with HTML too.
+
 ## Pagination
 
 List methods return the first page, a `Nohead::Page`. It's Enumerable: `each`, `map`, `first` and so on walk every item across pages, fetching the next page only when needed.

data/lib/nohead/client.rb

@@ -61,10 +61,13 @@ module Nohead
     # warnings::    Warn about deprecated operations and plan usage (once each).
     # on_retry::    Called with a RetryEvent before each retry's wait, for
     #               example to log it.
+    # rich_text::   How rich text fields read in the records and drafts
+    #               returned: "document" (the API's default), "html" or
+    #               "markdown". A method's own `rich_text:` wins.
     #
     # An empty string is the same as leaving an option out.
     def initialize(api_key: nil, base_url: nil, project_id: nil, max_retries: 2, timeout: 60,
-                   headers: {}, warnings: true, on_retry: nil, transport: Transport.new)
+                   headers: {}, warnings: true, on_retry: nil, rich_text: nil, transport: Transport.new)
       @api_key = present(api_key) || present(ENV.fetch("NOHEAD_API_KEY", nil)) or
         raise Error, "Missing API key: pass api_key or set NOHEAD_API_KEY"
       @base_url = checked_base_url(present(base_url) || DEFAULT_BASE_URL)
@@ -74,6 +77,7 @@ module Nohead
       @headers = merge_headers({}, headers.to_h)
       @warnings = warnings
       @on_retry = on_retry
+      @rich_text = present(rich_text)
       @transport = transport
       build_resources
     end
@@ -81,8 +85,11 @@ module Nohead
     # A copy of the client with other settings, which shares its transport
     # and project lookup: `nohead.with_options(timeout: 5).records.get(id)`.
     # `headers:` are added to the client's.
-    def with_options(timeout: @timeout, max_retries: @max_retries, headers: {}, on_retry: @on_retry)
-      dup.tap { |copy| copy.configure(timeout, max_retries, merge_headers(@headers, headers.to_h), on_retry) }
+    def with_options(timeout: @timeout, max_retries: @max_retries, headers: {}, on_retry: @on_retry,
+                     rich_text: @rich_text)
+      dup.tap do |copy|
+        copy.configure(timeout, max_retries, merge_headers(@headers, headers.to_h), on_retry, present(rich_text))
+      end
     end
 
     # Full-text search across the key's project (or some of its collections),
@@ -90,10 +97,11 @@ module Nohead
     # `published_at` ({ published_at: { exists: true } } for published
     # records), as records.list does. `collections` wins over a `collection`
     # filter.
-    def search(query, collections: nil, filter: nil, limit: nil, cursor: nil)
+    def search(query, collections: nil, filter: nil, limit: nil, cursor: nil, rich_text: nil)
       filter = filter.to_h.transform_keys(&:to_sym)
       filter = filter.merge(collection: { in: collections }) unless collections.nil?
-      paginate("projects_search", query: { q: query, filter: filter, limit: limit, cursor: cursor })
+      paginate("projects_search", query: { q: query, filter: filter, limit: limit, cursor: cursor },
+                                  rich_text: rich_text)
     end
 
     # The API key's project, from GET /v1/me the first time. Threads that
@@ -110,17 +118,18 @@ module Nohead
     # result. The resources call this; it is public for operations the SDK
     # does not wrap yet.
     def request(operation, path: {}, query: {}, body: nil, idempotency_key: nil,
-                change_note: nil, if_match: nil)
+                change_note: nil, if_match: nil, rich_text: nil)
       NoheadObject.wrap(exchange(operation, path: path, query: query, body: body, idempotency_key: idempotency_key,
-                                            change_note: change_note, if_match: if_match).first)
+                                            change_note: change_note, if_match: if_match, rich_text: rich_text).first)
     end
 
     # A list operation as a Page that fetches the following pages as needed.
-    def paginate(operation, path: {}, query: {})
+    def paginate(operation, path: {}, query: {}, rich_text: nil)
       params = query.dup
       cursor = params.delete(:cursor)
       fetch = lambda do |next_cursor|
-        list, status = exchange(operation, path: path, query: params.merge(cursor: next_cursor))
+        list, status = exchange(operation, path: path, query: params.merge(cursor: next_cursor),
+                                           rich_text: rich_text)
         unless list.is_a?(Hash) && list["data"].is_a?(Array) && list["meta"].is_a?(Hash)
           raise Error, "The API's response could not be read (HTTP #{status})"
         end
@@ -158,11 +167,12 @@ module Nohead
     protected
 
     # with_options' settings, on its copy.
-    def configure(timeout, max_retries, headers, on_retry)
+    def configure(timeout, max_retries, headers, on_retry, rich_text)
       @timeout = timeout
       @max_retries = max_retries
       @headers = headers
       @on_retry = on_retry
+      @rich_text = rich_text
     end
 
     private
@@ -189,9 +199,9 @@ module Nohead
 
     # The parsed body of a 2xx response, and its status.
     def exchange(operation, path: {}, query: {}, body: nil, idempotency_key: nil,
-                 change_note: nil, if_match: nil)
+                 change_note: nil, if_match: nil, rich_text: nil)
       method, template = OPERATIONS.fetch(operation)
-      url = build_url(template, path) + query_string(query)
+      url = build_url(template, path) + query_string(query.merge(rich_text_query(operation, rich_text)))
       headers = request_headers(method, body, idempotency_key, change_note, if_match)
       payload = body.nil? ? nil : JSON.generate(json_ready(body))
       attempt = 0
@@ -238,6 +248,15 @@ module Nohead
       @base_url + path
     end
 
+    # The request's `rich_text`, else the client's, for an operation that
+    # takes it. Others never send the client's.
+    def rich_text_query(operation, rich_text)
+      return { rich_text: present(rich_text) || @rich_text } if RICH_TEXT_OPERATIONS.include?(operation)
+      raise ArgumentError, "#{operation} does not take rich_text" if present(rich_text)
+
+      {}
+    end
+
     # Query parameters as the API reads them: hashes become key[sub]=...
     # (filter[price][lt]=50), arrays are comma-separated (expand=author,tags)
     # with \, for a comma inside a value and \\ for a backslash, times are

data/lib/nohead/operations.rb

@@ -97,4 +97,15 @@ module Nohead
 
   # The objects whose `data` is a record's field values.
   RECORD_DATA_OBJECTS = %w[draft record record_revision revert_preview].to_set.freeze
+
+  # The operations that take `rich_text`: how rich text fields read in the
+  # records and drafts they return.
+  RICH_TEXT_OPERATIONS = %w[
+    collections_search drafts_create drafts_discard drafts_get
+    drafts_list drafts_merge drafts_schedule drafts_unschedule
+    drafts_update projects_search record_drafts_list record_revisions_revert
+    records_bulk records_create records_delete records_get
+    records_list records_publish records_restore records_unpublish
+    records_update
+  ].to_set.freeze
 end

data/lib/nohead/resources/drafts.rb

@@ -5,57 +5,60 @@ module Nohead
     # Drafts: changes to a record's content that wait until they are merged
     # into it, now or at a set time, while the record keeps its current
     # content. A record has at most one. `draft` is a draft ID ("drf_..."),
-    # `record` a record ID and `collection` a collection ID or slug.
+    # `record` a record ID and `collection` a collection ID or slug. Every
+    # method takes `rich_text:`, as records' do.
     class Drafts < Resource
       # Starts the record's draft: `data` over the record's values, or with
       # `from_revision`, over an earlier revision's. A second draft raises
       # ConflictError (detail code `draft_exists`, with its `draft_id`).
-      def create(record, data: {}, from_revision: nil, idempotency_key: nil)
+      def create(record, data: {}, from_revision: nil, idempotency_key: nil, rich_text: nil)
         @client.request("drafts_create", path: { record_id: record },
                                          body: { data: data, from_revision: from_revision }.compact,
-                                         idempotency_key: idempotency_key)
+                                         idempotency_key: idempotency_key, rich_text: rich_text)
       end
 
       # A collection's drafts, most recently changed first. One record's
       # draft is `records.drafts(record)`.
-      def list(collection, sort: nil, limit: nil, cursor: nil)
+      def list(collection, sort: nil, limit: nil, cursor: nil, rich_text: nil)
         @client.paginate("drafts_list", path: { collection_id: collection },
-                                        query: { sort: sort, limit: limit, cursor: cursor })
+                                        query: { sort: sort, limit: limit, cursor: cursor }, rich_text: rich_text)
       end
 
       # With `data` as the record reads after the merge, for previews.
-      def get(draft, expand: nil)
-        @client.request("drafts_get", path: { draft_id: draft }, query: { expand: expand })
+      def get(draft, expand: nil, rich_text: nil)
+        @client.request("drafts_get", path: { draft_id: draft }, query: { expand: expand }, rich_text: rich_text)
       end
 
       # Sets the given fields (nil clears one), as a record update does.
-      def update(draft, data:, if_match: nil, idempotency_key: nil)
+      def update(draft, data:, if_match: nil, idempotency_key: nil, rich_text: nil)
         @client.request("drafts_update", path: { draft_id: draft }, body: { data: data },
-                                         if_match: if_match, idempotency_key: idempotency_key)
+                                         if_match: if_match, idempotency_key: idempotency_key, rich_text: rich_text)
       end
 
       # Deletes the draft for good; returns it as it was.
-      def discard(draft, if_match: nil, idempotency_key: nil)
+      def discard(draft, if_match: nil, idempotency_key: nil, rich_text: nil)
         @client.request("drafts_discard", path: { draft_id: draft }, if_match: if_match,
-                                          idempotency_key: idempotency_key)
+                                          idempotency_key: idempotency_key, rich_text: rich_text)
       end
 
       # Applies the draft to its record now, as one `merge` revision, and
       # returns the record. Content only: the record stays live or not.
-      def merge(draft, if_match: nil, idempotency_key: nil, change_note: nil)
+      def merge(draft, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil)
         @client.request("drafts_merge", path: { draft_id: draft }, if_match: if_match,
-                                        idempotency_key: idempotency_key, change_note: change_note)
+                                        idempotency_key: idempotency_key, change_note: change_note,
+                                        rich_text: rich_text)
       end
 
       # Merges the draft at `merge_at` (a Time or ISO 8601 string in the
       # future); returns the draft.
-      def schedule(draft, merge_at:, idempotency_key: nil)
+      def schedule(draft, merge_at:, idempotency_key: nil, rich_text: nil)
         @client.request("drafts_schedule", path: { draft_id: draft }, body: { merge_at: merge_at },
-                                           idempotency_key: idempotency_key)
+                                           idempotency_key: idempotency_key, rich_text: rich_text)
       end
 
-      def unschedule(draft, idempotency_key: nil)
-        @client.request("drafts_unschedule", path: { draft_id: draft }, idempotency_key: idempotency_key)
+      def unschedule(draft, idempotency_key: nil, rich_text: nil)
+        @client.request("drafts_unschedule", path: { draft_id: draft }, idempotency_key: idempotency_key,
+                                             rich_text: rich_text)
       end
     end
   end

data/lib/nohead/resources/records.rb

@@ -4,8 +4,8 @@ module Nohead
   module Resources
     # The base of the resources: each holds the client it sends requests with.
     class Resource
-      # Request options that are headers, not body fields.
-      OPTIONS = %i[change_note if_match].freeze
+      # Request options, not body fields.
+      OPTIONS = %i[change_note if_match rich_text].freeze
 
       def initialize(client)
         @client = client
@@ -17,8 +17,8 @@ module Nohead
 
       # The keyword arguments a method sends as the body. SDK options would
       # land there when the method doesn't take them (its operation doesn't
-      # declare the header), so they raise ArgumentError as Ruby does for
-      # unknown keywords.
+      # declare the header or query parameter), so they raise ArgumentError as
+      # Ruby does for unknown keywords.
       def body_of(params)
         option = OPTIONS.find { |name| params.key?(name) }
         raise ArgumentError, "unknown keyword: :#{option}" if option
@@ -48,56 +48,62 @@ module Nohead
       # A collection's records, newest first by default. `filter` holds
       # filters ({ published_at: { exists: true } } for published records),
       # `expand` relation or asset fields to embed under `expanded` (at most 5).
-      def list(collection, filter: nil, sort: nil, expand: nil, limit: nil, cursor: nil)
+      # Methods that return records or drafts take `rich_text:` ("document",
+      # "html" or "markdown"): how their rich text fields read.
+      def list(collection, filter: nil, sort: nil, expand: nil, limit: nil, cursor: nil, rich_text: nil)
         @client.paginate("records_list", path: { collection_id: collection }, query: {
                            filter: filter, sort: sort, expand: expand, limit: limit, cursor: cursor
-                         })
+                         }, rich_text: rich_text)
       end
 
       # A deleted record too, with `deleted_at` and `purge_after`.
-      def get(record, expand: nil)
-        @client.request("records_get", path: { record_id: record }, query: { expand: expand })
+      def get(record, expand: nil, rich_text: nil)
+        @client.request("records_get", path: { record_id: record }, query: { expand: expand }, rich_text: rich_text)
       end
 
       # Creates an unpublished record: create("posts", data: { title: "Hello" }).
       # With upsert_on:, the key of a unique field, it updates the record holding
       # that value instead, if one exists, so a sync can run again without
       # duplicates; if_match: then applies to that update.
-      def create(collection, if_match: nil, idempotency_key: nil, change_note: nil, **params)
+      def create(collection, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil, **params)
         @client.request("records_create", path: { collection_id: collection }, body: body_of(params),
                                           if_match: if_match, idempotency_key: idempotency_key,
-                                          change_note: change_note)
+                                          change_note: change_note, rich_text: rich_text)
       end
 
       # Sets the given fields (nil clears one); others keep their values.
-      def update(record, if_match: nil, idempotency_key: nil, change_note: nil, **params)
+      def update(record, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil, **params)
         @client.request("records_update", path: { record_id: record }, body: body_of(params),
                                           if_match: if_match, idempotency_key: idempotency_key,
-                                          change_note: change_note)
+                                          change_note: change_note, rich_text: rich_text)
       end
 
       # Soft-deletes the record: restore brings it back until its `purge_after`.
       # Deleting a deleted record changes nothing.
-      def delete(record, if_match: nil, idempotency_key: nil, change_note: nil)
+      def delete(record, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil)
         @client.request("records_delete", path: { record_id: record }, if_match: if_match,
-                                          idempotency_key: idempotency_key, change_note: change_note)
+                                          idempotency_key: idempotency_key, change_note: change_note,
+                                          rich_text: rich_text)
       end
 
-      def restore(record, if_match: nil, idempotency_key: nil, change_note: nil)
+      def restore(record, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil)
         @client.request("records_restore", path: { record_id: record }, if_match: if_match,
-                                           idempotency_key: idempotency_key, change_note: change_note)
+                                           idempotency_key: idempotency_key, change_note: change_note,
+                                           rich_text: rich_text)
       end
 
       # A live record with a pending draft raises ConflictError (detail code
       # `draft_pending`): publishing never merges a draft (drafts.merge does).
-      def publish(record, if_match: nil, idempotency_key: nil, change_note: nil)
+      def publish(record, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil)
         @client.request("records_publish", path: { record_id: record }, if_match: if_match,
-                                           idempotency_key: idempotency_key, change_note: change_note)
+                                           idempotency_key: idempotency_key, change_note: change_note,
+                                           rich_text: rich_text)
       end
 
-      def unpublish(record, if_match: nil, idempotency_key: nil, change_note: nil)
+      def unpublish(record, if_match: nil, idempotency_key: nil, change_note: nil, rich_text: nil)
         @client.request("records_unpublish", path: { record_id: record }, if_match: if_match,
-                                             idempotency_key: idempotency_key, change_note: change_note)
+                                             idempotency_key: idempotency_key, change_note: change_note,
+                                             rich_text: rich_text)
       end
 
       # What is live: since when, by whom, and the revision. Raises
@@ -130,8 +136,9 @@ module Nohead
       end
 
       # The record's drafts: at most one for now.
-      def drafts(record, limit: nil, cursor: nil)
-        @client.paginate("record_drafts_list", path: { record_id: record }, query: { limit: limit, cursor: cursor })
+      def drafts(record, limit: nil, cursor: nil, rich_text: nil)
+        @client.paginate("record_drafts_list", path: { record_id: record }, query: { limit: limit, cursor: cursor },
+                                               rich_text: rich_text)
       end
 
       # A collection's pending scheduled changes, soonest first: publishes,
@@ -149,9 +156,10 @@ module Nohead
 
       # Publishes, unpublishes, deletes, restores or updates up to 100 records.
       # Each record succeeds or fails on its own; see `results`.
-      def bulk(collection, idempotency_key: nil, change_note: nil, **params)
+      def bulk(collection, idempotency_key: nil, change_note: nil, rich_text: nil, **params)
         @client.request("records_bulk", path: { collection_id: collection }, body: body_of(params),
-                                        idempotency_key: idempotency_key, change_note: change_note)
+                                        idempotency_key: idempotency_key, change_note: change_note,
+                                        rich_text: rich_text)
       end
 
       # The changes between two revisions: diff(record, from: 1, to: 2).
@@ -161,11 +169,11 @@ module Nohead
 
       # Full-text search in one collection, matching its searchable fields, most
       # relevant first, through the first 1,000 hits.
-      def search(collection, query, filter: nil, sort: nil, expand: nil, limit: nil, cursor: nil)
+      def search(collection, query, filter: nil, sort: nil, expand: nil, limit: nil, cursor: nil, rich_text: nil)
         @client.paginate("collections_search", path: { collection_id: collection }, query: {
                            q: query, filter: filter, sort: sort, expand: expand, limit: limit,
                            cursor: cursor
-                         })
+                         }, rich_text: rich_text)
       end
     end
 
@@ -184,10 +192,12 @@ module Nohead
 
       # Restores the record's data as of `revision`, as a new revision. With
       # dry_run: true, previews it.
-      def revert(record, revision, dry_run: false, if_match: nil, idempotency_key: nil, change_note: nil)
+      def revert(record, revision, dry_run: false, if_match: nil, idempotency_key: nil, change_note: nil,
+                 rich_text: nil)
         @client.request("record_revisions_revert", path: { record_id: record, revision: revision },
                                                    query: { dry_run: dry_run || nil }, if_match: if_match,
-                                                   idempotency_key: idempotency_key, change_note: change_note)
+                                                   idempotency_key: idempotency_key, change_note: change_note,
+                                                   rich_text: rich_text)
       end
     end
 

data/lib/nohead/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nohead
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nohead
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Nohead